archastro.platform.v1.resources.kv

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: c7ca581aeeaa
  4
  5from __future__ import annotations
  6
  7from typing import Required, TypedDict
  8
  9from pydantic import BaseModel, Field
 10
 11from ...runtime.http_client import HttpClient, SyncHttpClient
 12from ...types.common import KeyValueStorageEntry, KeyValueStorageEntryPage
 13
 14
 15class KvCreateInput(TypedDict, total=False):
 16    "Create a key-value storage entry"
 17
 18    agent: str | None
 19    "Agent owner ID."
 20    key: Required[str]
 21    "Storage key for the entry. Must be a non-empty string unique to this user."
 22    org: str | None
 23    "Organization scope for the owner."
 24    system: bool | None
 25    "Select system ownership within the app or organization."
 26    team: str | None
 27    "Team owner ID."
 28    ttl_seconds: int | None
 29    "Positive lifetime in seconds; omitted means no expiry."
 30    user: str | None
 31    "User owner ID. Elevated callers may instead select team, agent, org, or system ownership."
 32    value: Required[str]
 33    "Value to store under `key`. Must be a non-empty string."
 34
 35
 36class KvUpsertInput(TypedDict, total=False):
 37    "Create or update a key-value storage entry"
 38
 39    agent: str | None
 40    "Agent owner ID."
 41    org: str | None
 42    "Organization scope for the owner."
 43    system: bool | None
 44    "Select system ownership within the app or organization."
 45    team: str | None
 46    "Team owner ID."
 47    ttl_seconds: int | None
 48    "Positive lifetime in seconds; omitted means no expiry."
 49    user: str | None
 50    "User owner ID. Elevated callers may instead select team, agent, org, or system ownership."
 51    value: Required[str]
 52    "New value to store under `key`. Must be a non-empty string. Replaces any existing value."
 53
 54
 55class KvDeleteResponse(BaseModel):
 56    """
 57    Successful response
 58    """
 59
 60    deleted: bool = Field(..., description="Always `true` when the deletion succeeds.")
 61    key: str = Field(..., description="Storage key of the deleted entry.")
 62
 63
 64class AsyncKvResource:
 65    def __init__(self, http: HttpClient):
 66        self._http = http
 67
 68    async def list(
 69        self,
 70        *,
 71        org: str | None = None,
 72        team: str | None = None,
 73        agent: str | None = None,
 74        system: bool | None = None,
 75        page: int | None = None,
 76        page_size: int | None = None,
 77        user: str | None = None,
 78        user_search: str | None = None,
 79        key: str | None = None,
 80    ) -> KeyValueStorageEntryPage:
 81        """
 82        List key-value storage entries
 83        Returns key-value storage entries in one of two modes depending on the caller's
 84        auth scope.
 85        **User-JWT callers** receive a flat list of all their own entries with no
 86        pagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`
 87        params are ignored.
 88        **Developer and server-to-server callers** receive a page-based paginated
 89        response across all users within the caller's app. Use `user` to scope results
 90        to a single user, `user_search` to do a substring match on email or full name,
 91        and `key` to filter entries whose key starts with the given prefix. Results are
 92        ordered by update time descending. Supplying org, team, agent, or system selects
 93        a single owner's flat list instead. Expired entries are excluded in every mode.
 94
 95        Args:
 96            org: Organization scope for the owner.
 97            team: Team owner ID.
 98            agent: Agent owner ID.
 99            system: Select system ownership within the app or organization.
100            page: Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.
101            page_size: Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.
102            user: Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.
103            user_search: Substring match against user email address and full name. Applies to developer and server-to-server callers only.
104            key: Prefix filter on the storage key. Returns only entries whose key starts with this string. Applies to developer and server-to-server callers only.
105
106        Returns:
107            Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers.
108        """
109        query: dict[str, object] = {}
110        if org is not None:
111            query["org"] = org
112        if team is not None:
113            query["team"] = team
114        if agent is not None:
115            query["agent"] = agent
116        if system is not None:
117            query["system"] = system
118        if page is not None:
119            query["page"] = page
120        if page_size is not None:
121            query["page_size"] = page_size
122        if user is not None:
123            query["user"] = user
124        if user_search is not None:
125            query["user_search"] = user_search
126        if key is not None:
127            query["key"] = key
128        return await self._http.request(
129            "/api/v1/kv",
130            query=query,
131            response_type=KeyValueStorageEntryPage,
132        )
133
134    async def create(self, input: KvCreateInput) -> KeyValueStorageEntry:
135        """
136        Create a key-value storage entry
137        Creates a key once per owner. An existing key returns HTTP 409 conflict, including expired rows awaiting sweep.
138        User-JWT callers use their own storage. Elevated callers select an owner with
139        system: true, team, user, or agent (in that priority order). An org alone selects
140        system ownership within that organization; all owners must be in the app scope.
141        Create and upsert accept a positive ttl_seconds; absent means no expiry.
142        Script binding (`kv.create`): the entry is owned by the triggering
143        automation's owner; scripts pass no owner params. A duplicate key
144        returns a script Err with code "conflict" instead of raising.
145
146        Args:
147            input: Request body.
148            input.agent: Agent owner ID.
149            input.key: Storage key for the entry. Must be a non-empty string unique to this user.
150            input.org: Organization scope for the owner.
151            input.system: Select system ownership within the app or organization.
152            input.team: Team owner ID.
153            input.ttl_seconds: Positive lifetime in seconds; omitted means no expiry.
154            input.user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
155            input.value: Value to store under `key`. Must be a non-empty string.
156
157        Returns:
158            The newly created key-value storage entry.
159        """
160        return await self._http.request(
161            "/api/v1/kv",
162            method="POST",
163            body=input,
164            response_type=KeyValueStorageEntry,
165        )
166
167    async def delete(self, key: str) -> KvDeleteResponse:
168        """
169        Delete a key-value storage entry
170        Deletes an unexpired entry by owner and key. Returns 204, or 404 when absent.
171        User-JWT callers use their own storage. Elevated callers select an owner with
172        system: true, team, user, or agent (in that priority order). An org alone selects
173        system ownership within that organization; all owners must be in the app scope.
174        Create and upsert accept a positive ttl_seconds; absent means no expiry.
175        Script binding (`kv.delete`): removes the entry owned by the triggering
176        automation's owner; scripts pass no owner params.
177
178        Args:
179            key: Storage key of the entry to delete. Must be a non-empty string.
180
181        Returns:
182            Successful response
183        """
184        return await self._http.request(
185            f"/api/v1/kv/{key}",
186            method="DELETE",
187            response_type=KvDeleteResponse,
188        )
189
190    async def get(
191        self,
192        key: str,
193        *,
194        org: str | None = None,
195        team: str | None = None,
196        agent: str | None = None,
197        system: bool | None = None,
198        user: str | None = None,
199    ) -> KeyValueStorageEntry:
200        """
201        Retrieve a key-value storage entry
202        Returns an unexpired entry by owner and key, or 404.
203        User-JWT callers use their own storage. Elevated callers select an owner with
204        system: true, team, user, or agent (in that priority order). An org alone selects
205        system ownership within that organization; all owners must be in the app scope.
206        Create and upsert accept a positive ttl_seconds; absent means no expiry.
207        Script binding (`kv.get`): reads the entry owned by the triggering
208        automation's owner; scripts pass no owner params.
209
210        Args:
211            key: Storage key of the entry to retrieve. Must be a non-empty string.
212            org: Organization scope for the owner.
213            team: Team owner ID.
214            agent: Agent owner ID.
215            system: Select system ownership within the app or organization.
216            user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
217
218        Returns:
219            The key-value storage entry for the given key.
220        """
221        query: dict[str, object] = {}
222        if org is not None:
223            query["org"] = org
224        if team is not None:
225            query["team"] = team
226        if agent is not None:
227            query["agent"] = agent
228        if system is not None:
229            query["system"] = system
230        if user is not None:
231            query["user"] = user
232        return await self._http.request(
233            f"/api/v1/kv/{key}",
234            query=query,
235            response_type=KeyValueStorageEntry,
236        )
237
238    async def upsert(self, key: str, input: KvUpsertInput) -> KeyValueStorageEntry:
239        """
240        Create or update a key-value storage entry
241        Creates or replaces a value and its expiry. Omitted ttl_seconds clears any previous expiry.
242        User-JWT callers use their own storage. Elevated callers select an owner with
243        system: true, team, user, or agent (in that priority order). An org alone selects
244        system ownership within that organization; all owners must be in the app scope.
245        Create and upsert accept a positive ttl_seconds; absent means no expiry.
246        Script binding (`kv.upsert`): overwrites the entry owned by the triggering
247        automation's owner; scripts pass no owner params.
248
249        Args:
250            key: Storage key to create or overwrite. Must be a non-empty string.
251            input: Request body.
252            input.agent: Agent owner ID.
253            input.org: Organization scope for the owner.
254            input.system: Select system ownership within the app or organization.
255            input.team: Team owner ID.
256            input.ttl_seconds: Positive lifetime in seconds; omitted means no expiry.
257            input.user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
258            input.value: New value to store under `key`. Must be a non-empty string. Replaces any existing value.
259
260        Returns:
261            The created or updated key-value storage entry.
262        """
263        return await self._http.request(
264            f"/api/v1/kv/{key}",
265            method="PUT",
266            body=input,
267            response_type=KeyValueStorageEntry,
268        )
269
270
271class KvResource:
272    def __init__(self, http: SyncHttpClient):
273        self._http = http
274
275    def list(
276        self,
277        *,
278        org: str | None = None,
279        team: str | None = None,
280        agent: str | None = None,
281        system: bool | None = None,
282        page: int | None = None,
283        page_size: int | None = None,
284        user: str | None = None,
285        user_search: str | None = None,
286        key: str | None = None,
287    ) -> KeyValueStorageEntryPage:
288        """
289        List key-value storage entries
290        Returns key-value storage entries in one of two modes depending on the caller's
291        auth scope.
292        **User-JWT callers** receive a flat list of all their own entries with no
293        pagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`
294        params are ignored.
295        **Developer and server-to-server callers** receive a page-based paginated
296        response across all users within the caller's app. Use `user` to scope results
297        to a single user, `user_search` to do a substring match on email or full name,
298        and `key` to filter entries whose key starts with the given prefix. Results are
299        ordered by update time descending. Supplying org, team, agent, or system selects
300        a single owner's flat list instead. Expired entries are excluded in every mode.
301
302        Args:
303            org: Organization scope for the owner.
304            team: Team owner ID.
305            agent: Agent owner ID.
306            system: Select system ownership within the app or organization.
307            page: Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.
308            page_size: Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.
309            user: Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.
310            user_search: Substring match against user email address and full name. Applies to developer and server-to-server callers only.
311            key: Prefix filter on the storage key. Returns only entries whose key starts with this string. Applies to developer and server-to-server callers only.
312
313        Returns:
314            Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers.
315        """
316        query: dict[str, object] = {}
317        if org is not None:
318            query["org"] = org
319        if team is not None:
320            query["team"] = team
321        if agent is not None:
322            query["agent"] = agent
323        if system is not None:
324            query["system"] = system
325        if page is not None:
326            query["page"] = page
327        if page_size is not None:
328            query["page_size"] = page_size
329        if user is not None:
330            query["user"] = user
331        if user_search is not None:
332            query["user_search"] = user_search
333        if key is not None:
334            query["key"] = key
335        return self._http.request(
336            "/api/v1/kv",
337            query=query,
338            response_type=KeyValueStorageEntryPage,
339        )
340
341    def create(self, input: KvCreateInput) -> KeyValueStorageEntry:
342        """
343        Create a key-value storage entry
344        Creates a key once per owner. An existing key returns HTTP 409 conflict, including expired rows awaiting sweep.
345        User-JWT callers use their own storage. Elevated callers select an owner with
346        system: true, team, user, or agent (in that priority order). An org alone selects
347        system ownership within that organization; all owners must be in the app scope.
348        Create and upsert accept a positive ttl_seconds; absent means no expiry.
349        Script binding (`kv.create`): the entry is owned by the triggering
350        automation's owner; scripts pass no owner params. A duplicate key
351        returns a script Err with code "conflict" instead of raising.
352
353        Args:
354            input: Request body.
355            input.agent: Agent owner ID.
356            input.key: Storage key for the entry. Must be a non-empty string unique to this user.
357            input.org: Organization scope for the owner.
358            input.system: Select system ownership within the app or organization.
359            input.team: Team owner ID.
360            input.ttl_seconds: Positive lifetime in seconds; omitted means no expiry.
361            input.user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
362            input.value: Value to store under `key`. Must be a non-empty string.
363
364        Returns:
365            The newly created key-value storage entry.
366        """
367        return self._http.request(
368            "/api/v1/kv",
369            method="POST",
370            body=input,
371            response_type=KeyValueStorageEntry,
372        )
373
374    def delete(self, key: str) -> KvDeleteResponse:
375        """
376        Delete a key-value storage entry
377        Deletes an unexpired entry by owner and key. Returns 204, or 404 when absent.
378        User-JWT callers use their own storage. Elevated callers select an owner with
379        system: true, team, user, or agent (in that priority order). An org alone selects
380        system ownership within that organization; all owners must be in the app scope.
381        Create and upsert accept a positive ttl_seconds; absent means no expiry.
382        Script binding (`kv.delete`): removes the entry owned by the triggering
383        automation's owner; scripts pass no owner params.
384
385        Args:
386            key: Storage key of the entry to delete. Must be a non-empty string.
387
388        Returns:
389            Successful response
390        """
391        return self._http.request(
392            f"/api/v1/kv/{key}",
393            method="DELETE",
394            response_type=KvDeleteResponse,
395        )
396
397    def get(
398        self,
399        key: str,
400        *,
401        org: str | None = None,
402        team: str | None = None,
403        agent: str | None = None,
404        system: bool | None = None,
405        user: str | None = None,
406    ) -> KeyValueStorageEntry:
407        """
408        Retrieve a key-value storage entry
409        Returns an unexpired entry by owner and key, or 404.
410        User-JWT callers use their own storage. Elevated callers select an owner with
411        system: true, team, user, or agent (in that priority order). An org alone selects
412        system ownership within that organization; all owners must be in the app scope.
413        Create and upsert accept a positive ttl_seconds; absent means no expiry.
414        Script binding (`kv.get`): reads the entry owned by the triggering
415        automation's owner; scripts pass no owner params.
416
417        Args:
418            key: Storage key of the entry to retrieve. Must be a non-empty string.
419            org: Organization scope for the owner.
420            team: Team owner ID.
421            agent: Agent owner ID.
422            system: Select system ownership within the app or organization.
423            user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
424
425        Returns:
426            The key-value storage entry for the given key.
427        """
428        query: dict[str, object] = {}
429        if org is not None:
430            query["org"] = org
431        if team is not None:
432            query["team"] = team
433        if agent is not None:
434            query["agent"] = agent
435        if system is not None:
436            query["system"] = system
437        if user is not None:
438            query["user"] = user
439        return self._http.request(
440            f"/api/v1/kv/{key}",
441            query=query,
442            response_type=KeyValueStorageEntry,
443        )
444
445    def upsert(self, key: str, input: KvUpsertInput) -> KeyValueStorageEntry:
446        """
447        Create or update a key-value storage entry
448        Creates or replaces a value and its expiry. Omitted ttl_seconds clears any previous expiry.
449        User-JWT callers use their own storage. Elevated callers select an owner with
450        system: true, team, user, or agent (in that priority order). An org alone selects
451        system ownership within that organization; all owners must be in the app scope.
452        Create and upsert accept a positive ttl_seconds; absent means no expiry.
453        Script binding (`kv.upsert`): overwrites the entry owned by the triggering
454        automation's owner; scripts pass no owner params.
455
456        Args:
457            key: Storage key to create or overwrite. Must be a non-empty string.
458            input: Request body.
459            input.agent: Agent owner ID.
460            input.org: Organization scope for the owner.
461            input.system: Select system ownership within the app or organization.
462            input.team: Team owner ID.
463            input.ttl_seconds: Positive lifetime in seconds; omitted means no expiry.
464            input.user: User owner ID. Elevated callers may instead select team, agent, org, or system ownership.
465            input.value: New value to store under `key`. Must be a non-empty string. Replaces any existing value.
466
467        Returns:
468            The created or updated key-value storage entry.
469        """
470        return self._http.request(
471            f"/api/v1/kv/{key}",
472            method="PUT",
473            body=input,
474            response_type=KeyValueStorageEntry,
475        )