archastro.platform.v1.resources.custom_objects

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: c5a3abd0b2ab
  4
  5from __future__ import annotations
  6
  7import builtins
  8from datetime import datetime
  9from typing import Any, Required, TypedDict
 10
 11from pydantic import BaseModel, Field
 12
 13from ...runtime.http_client import HttpClient, SyncHttpClient
 14from ...types.common import CustomObject, CustomObjectListResponse
 15
 16
 17class CustomObjectCreateInput(TypedDict, total=False):
 18    "Create a custom object"
 19
 20    agent: str | None
 21    "Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied."
 22    fields: Required[dict[str, Any]]
 23    "Key-value map of field values for the new object. Must conform to the schema's field definitions."
 24    org: str | None
 25    "Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects."
 26    system: bool | None
 27    "When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission."
 28    team: str | None
 29    "Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`."
 30    type: Required[str]
 31    "Schema type identifier (`lookup_key`) that defines the object's shape and validation rules."
 32    upsert: bool | None
 33    "When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create."
 34    user: str | None
 35    "User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set."
 36
 37
 38class CustomObjectReplaceInput(TypedDict, total=False):
 39    "Update a custom object"
 40
 41    field_ops: dict[str, Any] | None
 42    "Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`."
 43    fields: Required[dict[str, Any]]
 44    "Key-value map of field values to merge into the object. Only the supplied keys are affected."
 45    type: str | None
 46    "Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only."
 47
 48
 49class CustomObjectDeleteResponse(BaseModel):
 50    """
 51    Successful response
 52    """
 53
 54    deleted: bool = Field(..., description="Always `true` when the deletion succeeds.")
 55    id: str = Field(..., description="ID of the deleted custom object (`cobj_...`).")
 56
 57
 58class CustomObjectReplaceResponseData(BaseModel):
 59    created_at: datetime | None = Field(
 60        default=None, description="When the custom object was created (ISO 8601)."
 61    )
 62    fields: dict[str, Any] | None = Field(
 63        default=None,
 64        description="Map of field names to their current values as defined by the object's schema type.",
 65    )
 66    id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).")
 67    org: str | None = Field(
 68        default=None, description="ID of the organization this object belongs to (`org_...`)."
 69    )
 70    row_key: str | None = Field(
 71        default=None,
 72        description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.",
 73    )
 74    sandbox: str | None = Field(
 75        default=None,
 76        description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.",
 77    )
 78    schema_type: str | None = Field(
 79        default=None,
 80        description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.",
 81    )
 82    team: str | None = Field(
 83        default=None,
 84        description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.",
 85    )
 86    updated_at: datetime | None = Field(
 87        default=None,
 88        description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.",
 89    )
 90    user: str | None = Field(
 91        default=None,
 92        description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.",
 93    )
 94    version: int | None = Field(
 95        default=None,
 96        description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.",
 97    )
 98
 99
100class CustomObjectReplaceResponse(BaseModel):
101    """
102    Successful response
103    """
104
105    data: CustomObjectReplaceResponseData = Field(
106        ..., description="The custom object after the update has been applied."
107    )
108    meta: dict[str, Any] | None = Field(
109        default=None, description="Version metadata for the updated object."
110    )
111
112
113class AsyncCustomObjectResource:
114    def __init__(self, http: HttpClient):
115        self._http = http
116
117    async def list(
118        self,
119        type: str,
120        *,
121        row_key: str | None = None,
122        sort_key: builtins.list[str] | None = None,
123        team: builtins.list[str] | None = None,
124        user: builtins.list[str] | None = None,
125        agent: builtins.list[str] | None = None,
126        org: builtins.list[str] | None = None,
127        query: str | None = None,
128        page: int | None = None,
129        page_size: int | None = None,
130    ) -> CustomObjectListResponse:
131        """
132        List custom objects
133        Returns a paginated list of custom objects of the given schema type that are
134        visible to the authenticated viewer, ordered by creation time descending.
135        Results span all ownership types (team-owned, user-owned, agent-owned, and
136        system-owned) that the viewer has access to.
137        Use the `row_key` param to perform an exact-match partition lookup. You may
138        additionally supply `sort_key` to narrow within that partition `sort_key`
139        requires `row_key` and the request returns 400 if `sort_key` is provided
140        alone. Owner filters (`team`, `user`, `agent`, `org`) are additive: each
141        accepts an array of IDs and returns objects matching any of the supplied
142        values.
143        When `query` is supplied, results are ranked by full-text relevance
144        (descending `ts_rank`) rather than creation time.
145
146        Args:
147            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned.
148            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
149            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
150            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
151            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
152            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
153            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
154            query: Full-text search string matched against the schema's configured search fields. When supplied, results are ordered by relevance score descending instead of creation time descending.
155            page: Page number to retrieve (1-indexed). Defaults to `1`.
156            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
157
158        Returns:
159            Paginated list of custom objects matching the supplied filters.
160        """
161        query: dict[str, object] = {}
162        query["type"] = type
163        if row_key is not None:
164            query["row_key"] = row_key
165        if sort_key is not None:
166            query["sort_key"] = sort_key
167        if team is not None:
168            query["team"] = team
169        if user is not None:
170            query["user"] = user
171        if agent is not None:
172            query["agent"] = agent
173        if org is not None:
174            query["org"] = org
175        if query is not None:
176            query["query"] = query
177        if page is not None:
178            query["page"] = page
179        if page_size is not None:
180            query["page_size"] = page_size
181        return await self._http.request(
182            "/api/v1/custom_objects",
183            query=query,
184            response_type=CustomObjectListResponse,
185        )
186
187    async def create(self, input: CustomObjectCreateInput) -> CustomObject:
188        """
189        Create a custom object
190        Creates a new custom object of the given schema type and returns the
191        persisted object. The caller must be authenticated and authorized to create
192        objects of the specified type.
193        Owner resolution follows a priority order: if `team` is supplied the object
194        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
195        supplied it is agent-owned; otherwise the object is owned by the authenticated
196        user. Pass `system: true` explicitly to force system ownership this requires
197        elevated API credentials and returns 403 if the caller lacks permission.
198        If the schema declares a `row_key` (and optionally a `sort_key`), you may
199        pass `upsert: true` to update an existing object at that key instead of
200        receiving a 409 Conflict. The response status is `200` on an update and
201        `201` on a new create.
202
203        Args:
204            input: Request body.
205            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
206            input.fields: Key-value map of field values for the new object. Must conform to the schema's field definitions.
207            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
208            input.system: When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission.
209            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
210            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules.
211            input.upsert: When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create.
212            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
213
214        Returns:
215            The created (or upserted) custom object.
216        """
217        return await self._http.request(
218            "/api/v1/custom_objects",
219            method="POST",
220            body=input,
221            response_type=CustomObject,
222        )
223
224    async def delete(self, object: str) -> CustomObjectDeleteResponse:
225        """
226        Delete a custom object
227        Permanently deletes the custom object identified by `object`. The caller
228        must be authenticated and have permission to delete the object.
229        On success, returns a confirmation payload containing the deleted object's
230        ID so callers can confirm the deletion without a follow-up fetch.
231        Attempting to delete an object that does not exist or has already been
232        deleted returns 404.
233
234        Args:
235            object: Custom object ID (`cobj_...`) of the object to delete.
236
237        Returns:
238            Successful response
239        """
240        return await self._http.request(
241            f"/api/v1/custom_objects/{object}",
242            method="DELETE",
243            response_type=CustomObjectDeleteResponse,
244        )
245
246    async def get(self, object: str, *, type: str | None = None) -> CustomObject:
247        """
248        Retrieve a custom object
249        Returns a single custom object identified by its ID. The authenticated viewer
250        must have visibility access to the object.
251        Returns 404 if the object does not exist, has been deleted, or is not
252        visible to the viewer.
253
254        Args:
255            object: Custom object ID (`cobj_...`) to retrieve.
256            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
257
258        Returns:
259            The requested custom object.
260        """
261        query: dict[str, object] = {}
262        if type is not None:
263            query["type"] = type
264        return await self._http.request(
265            f"/api/v1/custom_objects/{object}",
266            query=query,
267            response_type=CustomObject,
268        )
269
270    async def replace(
271        self, object: str, input: CustomObjectReplaceInput
272    ) -> CustomObjectReplaceResponse:
273        """
274        Update a custom object
275        Updates the fields of an existing custom object and returns the updated
276        object along with its new version number. The authenticated viewer must have
277        permission to modify the object.
278        You may supply `fields` (a full or partial key-value map to merge into the
279        object), `field_ops` (granular array operations per field), or both but
280        the same field name must not appear in both, which returns 422. Returns 404
281        if the object does not exist or has been deleted.
282
283        Args:
284            object: Custom object ID (`cobj_...`) to update.
285            input: Request body.
286            input.field_ops: Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`.
287            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
288            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
289
290        Returns:
291            Successful response
292        """
293        return await self._http.request(
294            f"/api/v1/custom_objects/{object}",
295            method="PUT",
296            body=input,
297            response_type=CustomObjectReplaceResponse,
298        )
299
300
301class CustomObjectResource:
302    def __init__(self, http: SyncHttpClient):
303        self._http = http
304
305    def list(
306        self,
307        type: str,
308        *,
309        row_key: str | None = None,
310        sort_key: builtins.list[str] | None = None,
311        team: builtins.list[str] | None = None,
312        user: builtins.list[str] | None = None,
313        agent: builtins.list[str] | None = None,
314        org: builtins.list[str] | None = None,
315        query: str | None = None,
316        page: int | None = None,
317        page_size: int | None = None,
318    ) -> CustomObjectListResponse:
319        """
320        List custom objects
321        Returns a paginated list of custom objects of the given schema type that are
322        visible to the authenticated viewer, ordered by creation time descending.
323        Results span all ownership types (team-owned, user-owned, agent-owned, and
324        system-owned) that the viewer has access to.
325        Use the `row_key` param to perform an exact-match partition lookup. You may
326        additionally supply `sort_key` to narrow within that partition `sort_key`
327        requires `row_key` and the request returns 400 if `sort_key` is provided
328        alone. Owner filters (`team`, `user`, `agent`, `org`) are additive: each
329        accepts an array of IDs and returns objects matching any of the supplied
330        values.
331        When `query` is supplied, results are ranked by full-text relevance
332        (descending `ts_rank`) rather than creation time.
333
334        Args:
335            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned.
336            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
337            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
338            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
339            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
340            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
341            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
342            query: Full-text search string matched against the schema's configured search fields. When supplied, results are ordered by relevance score descending instead of creation time descending.
343            page: Page number to retrieve (1-indexed). Defaults to `1`.
344            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
345
346        Returns:
347            Paginated list of custom objects matching the supplied filters.
348        """
349        query: dict[str, object] = {}
350        query["type"] = type
351        if row_key is not None:
352            query["row_key"] = row_key
353        if sort_key is not None:
354            query["sort_key"] = sort_key
355        if team is not None:
356            query["team"] = team
357        if user is not None:
358            query["user"] = user
359        if agent is not None:
360            query["agent"] = agent
361        if org is not None:
362            query["org"] = org
363        if query is not None:
364            query["query"] = query
365        if page is not None:
366            query["page"] = page
367        if page_size is not None:
368            query["page_size"] = page_size
369        return self._http.request(
370            "/api/v1/custom_objects",
371            query=query,
372            response_type=CustomObjectListResponse,
373        )
374
375    def create(self, input: CustomObjectCreateInput) -> CustomObject:
376        """
377        Create a custom object
378        Creates a new custom object of the given schema type and returns the
379        persisted object. The caller must be authenticated and authorized to create
380        objects of the specified type.
381        Owner resolution follows a priority order: if `team` is supplied the object
382        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
383        supplied it is agent-owned; otherwise the object is owned by the authenticated
384        user. Pass `system: true` explicitly to force system ownership this requires
385        elevated API credentials and returns 403 if the caller lacks permission.
386        If the schema declares a `row_key` (and optionally a `sort_key`), you may
387        pass `upsert: true` to update an existing object at that key instead of
388        receiving a 409 Conflict. The response status is `200` on an update and
389        `201` on a new create.
390
391        Args:
392            input: Request body.
393            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
394            input.fields: Key-value map of field values for the new object. Must conform to the schema's field definitions.
395            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
396            input.system: When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission.
397            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
398            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules.
399            input.upsert: When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create.
400            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
401
402        Returns:
403            The created (or upserted) custom object.
404        """
405        return self._http.request(
406            "/api/v1/custom_objects",
407            method="POST",
408            body=input,
409            response_type=CustomObject,
410        )
411
412    def delete(self, object: str) -> CustomObjectDeleteResponse:
413        """
414        Delete a custom object
415        Permanently deletes the custom object identified by `object`. The caller
416        must be authenticated and have permission to delete the object.
417        On success, returns a confirmation payload containing the deleted object's
418        ID so callers can confirm the deletion without a follow-up fetch.
419        Attempting to delete an object that does not exist or has already been
420        deleted returns 404.
421
422        Args:
423            object: Custom object ID (`cobj_...`) of the object to delete.
424
425        Returns:
426            Successful response
427        """
428        return self._http.request(
429            f"/api/v1/custom_objects/{object}",
430            method="DELETE",
431            response_type=CustomObjectDeleteResponse,
432        )
433
434    def get(self, object: str, *, type: str | None = None) -> CustomObject:
435        """
436        Retrieve a custom object
437        Returns a single custom object identified by its ID. The authenticated viewer
438        must have visibility access to the object.
439        Returns 404 if the object does not exist, has been deleted, or is not
440        visible to the viewer.
441
442        Args:
443            object: Custom object ID (`cobj_...`) to retrieve.
444            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
445
446        Returns:
447            The requested custom object.
448        """
449        query: dict[str, object] = {}
450        if type is not None:
451            query["type"] = type
452        return self._http.request(
453            f"/api/v1/custom_objects/{object}",
454            query=query,
455            response_type=CustomObject,
456        )
457
458    def replace(self, object: str, input: CustomObjectReplaceInput) -> CustomObjectReplaceResponse:
459        """
460        Update a custom object
461        Updates the fields of an existing custom object and returns the updated
462        object along with its new version number. The authenticated viewer must have
463        permission to modify the object.
464        You may supply `fields` (a full or partial key-value map to merge into the
465        object), `field_ops` (granular array operations per field), or both but
466        the same field name must not appear in both, which returns 422. Returns 404
467        if the object does not exist or has been deleted.
468
469        Args:
470            object: Custom object ID (`cobj_...`) to update.
471            input: Request body.
472            input.field_ops: Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`.
473            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
474            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
475
476        Returns:
477            Successful response
478        """
479        return self._http.request(
480            f"/api/v1/custom_objects/{object}",
481            method="PUT",
482            body=input,
483            response_type=CustomObjectReplaceResponse,
484        )