archastro.platform.v1.resources.kv

  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: bc46a156c11b
  4
  5from __future__ import annotations
  6
  7from typing import Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import KeyValueStorageEntry, KeyValueStorageEntryPage
 11
 12
 13class KvCreateInput(TypedDict, total=False):
 14    "Create a key-value storage entry"
 15
 16    key: Required[str]
 17    "Storage key for the entry. Must be a non-empty string unique to this user."
 18    user: str | None
 19    "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers."
 20    value: Required[str]
 21    "Value to store under `key`. Must be a non-empty string."
 22
 23
 24class KvUpsertInput(TypedDict, total=False):
 25    "Create or update a key-value storage entry"
 26
 27    user: str | None
 28    "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers."
 29    value: Required[str]
 30    "New value to store under `key`. Must be a non-empty string. Replaces any existing value."
 31
 32
 33class AsyncKvResource:
 34    def __init__(self, http: HttpClient):
 35        self._http = http
 36
 37    async def list(
 38        self,
 39        *,
 40        page: int | None = None,
 41        page_size: int | None = None,
 42        user: str | None = None,
 43        user_search: str | None = None,
 44        key: str | None = None,
 45    ) -> KeyValueStorageEntryPage:
 46        """
 47        List key-value storage entries
 48        Returns key-value storage entries in one of two modes depending on the caller's
 49        auth scope.
 50        **User-JWT callers** receive a flat list of all their own entries with no
 51        pagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`
 52        params are ignored.
 53        **Developer and server-to-server callers** receive a page-based paginated
 54        response across all users within the caller's app. Use `user` to scope results
 55        to a single user, `user_search` to do a substring match on email or full name,
 56        and `key` to filter entries whose key starts with the given prefix. Results are
 57        ordered by creation time descending.
 58
 59        Args:
 60            page: Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.
 61            page_size: Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.
 62            user: Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.
 63            user_search: Substring match against user email address and full name. Applies to developer and server-to-server callers only.
 64            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.
 65
 66        Returns:
 67            Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers.
 68        """
 69        query: dict[str, object] = {}
 70        if page is not None:
 71            query["page"] = page
 72        if page_size is not None:
 73            query["page_size"] = page_size
 74        if user is not None:
 75            query["user"] = user
 76        if user_search is not None:
 77            query["user_search"] = user_search
 78        if key is not None:
 79            query["key"] = key
 80        return await self._http.request(
 81            "/api/v1/kv",
 82            query=query,
 83            response_type=KeyValueStorageEntryPage,
 84        )
 85
 86    async def create(self, input: KvCreateInput) -> KeyValueStorageEntry:
 87        """
 88        Create a key-value storage entry
 89        Creates a new key-value storage entry for the target user under the given key.
 90        The key must not already exist for this user; use the upsert endpoint to create
 91        or overwrite in a single call.
 92        End-user (user-JWT) callers always write to their own storage. Developer and
 93        server-to-server callers must supply a `user` param identifying the target user
 94        within their app's scope. Attempting to write for a user in a different app
 95        returns 404.
 96
 97        Args:
 98            input: Request body.
 99            input.key: Storage key for the entry. Must be a non-empty string unique to this user.
100            input.user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
101            input.value: Value to store under `key`. Must be a non-empty string.
102
103        Returns:
104            The newly created key-value storage entry.
105        """
106        return await self._http.request(
107            "/api/v1/kv",
108            method="POST",
109            body=input,
110            response_type=KeyValueStorageEntry,
111        )
112
113    async def delete(self, key: str) -> None:
114        """
115        Delete a key-value storage entry
116        Permanently deletes the key-value storage entry identified by `key` for the
117        target user. Returns 204 No Content on success and 404 if the entry does not
118        exist.
119        End-user (user-JWT) callers can only delete entries they own. Developer and
120        server-to-server callers must supply a `user` param identifying the target user
121        within their app's scope.
122
123        Args:
124            key: Storage key of the entry to delete. Must be a non-empty string.
125
126        Returns:
127            Empty response body. HTTP 204 No Content on success.
128        """
129        await self._http.request(f"/api/v1/kv/{key}", method="DELETE")
130
131    async def get(self, key: str, *, user: str | None = None) -> KeyValueStorageEntry:
132        """
133        Retrieve a key-value storage entry
134        Returns the key-value storage entry identified by `key` for the target user.
135        Returns 404 if no entry exists for that key.
136        End-user (user-JWT) callers retrieve entries from their own storage. Developer
137        and server-to-server callers must supply a `user` param identifying the target
138        user within their app's scope.
139
140        Args:
141            key: Storage key of the entry to retrieve. Must be a non-empty string.
142            user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
143
144        Returns:
145            The key-value storage entry for the given key.
146        """
147        query: dict[str, object] = {}
148        if user is not None:
149            query["user"] = user
150        return await self._http.request(
151            f"/api/v1/kv/{key}",
152            query=query,
153            response_type=KeyValueStorageEntry,
154        )
155
156    async def upsert(self, key: str, input: KvUpsertInput) -> KeyValueStorageEntry:
157        """
158        Create or update a key-value storage entry
159        Creates a new key-value storage entry for the given `key`, or overwrites the
160        value if an entry already exists. This is the idempotent alternative to the
161        create endpoint: safe to call regardless of whether the key already exists.
162        End-user (user-JWT) callers always write to their own storage. Developer and
163        server-to-server callers must supply a `user` param identifying the target user
164        within their app's scope. Attempting to write for a user in a different app
165        returns 404.
166
167        Args:
168            key: Storage key to create or overwrite. Must be a non-empty string.
169            input: Request body.
170            input.user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
171            input.value: New value to store under `key`. Must be a non-empty string. Replaces any existing value.
172
173        Returns:
174            The created or updated key-value storage entry.
175        """
176        return await self._http.request(
177            f"/api/v1/kv/{key}",
178            method="PUT",
179            body=input,
180            response_type=KeyValueStorageEntry,
181        )
182
183
184class KvResource:
185    def __init__(self, http: SyncHttpClient):
186        self._http = http
187
188    def list(
189        self,
190        *,
191        page: int | None = None,
192        page_size: int | None = None,
193        user: str | None = None,
194        user_search: str | None = None,
195        key: str | None = None,
196    ) -> KeyValueStorageEntryPage:
197        """
198        List key-value storage entries
199        Returns key-value storage entries in one of two modes depending on the caller's
200        auth scope.
201        **User-JWT callers** receive a flat list of all their own entries with no
202        pagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`
203        params are ignored.
204        **Developer and server-to-server callers** receive a page-based paginated
205        response across all users within the caller's app. Use `user` to scope results
206        to a single user, `user_search` to do a substring match on email or full name,
207        and `key` to filter entries whose key starts with the given prefix. Results are
208        ordered by creation time descending.
209
210        Args:
211            page: Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.
212            page_size: Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.
213            user: Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.
214            user_search: Substring match against user email address and full name. Applies to developer and server-to-server callers only.
215            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.
216
217        Returns:
218            Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers.
219        """
220        query: dict[str, object] = {}
221        if page is not None:
222            query["page"] = page
223        if page_size is not None:
224            query["page_size"] = page_size
225        if user is not None:
226            query["user"] = user
227        if user_search is not None:
228            query["user_search"] = user_search
229        if key is not None:
230            query["key"] = key
231        return self._http.request(
232            "/api/v1/kv",
233            query=query,
234            response_type=KeyValueStorageEntryPage,
235        )
236
237    def create(self, input: KvCreateInput) -> KeyValueStorageEntry:
238        """
239        Create a key-value storage entry
240        Creates a new key-value storage entry for the target user under the given key.
241        The key must not already exist for this user; use the upsert endpoint to create
242        or overwrite in a single call.
243        End-user (user-JWT) callers always write to their own storage. Developer and
244        server-to-server callers must supply a `user` param identifying the target user
245        within their app's scope. Attempting to write for a user in a different app
246        returns 404.
247
248        Args:
249            input: Request body.
250            input.key: Storage key for the entry. Must be a non-empty string unique to this user.
251            input.user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
252            input.value: Value to store under `key`. Must be a non-empty string.
253
254        Returns:
255            The newly created key-value storage entry.
256        """
257        return self._http.request(
258            "/api/v1/kv",
259            method="POST",
260            body=input,
261            response_type=KeyValueStorageEntry,
262        )
263
264    def delete(self, key: str) -> None:
265        """
266        Delete a key-value storage entry
267        Permanently deletes the key-value storage entry identified by `key` for the
268        target user. Returns 204 No Content on success and 404 if the entry does not
269        exist.
270        End-user (user-JWT) callers can only delete entries they own. Developer and
271        server-to-server callers must supply a `user` param identifying the target user
272        within their app's scope.
273
274        Args:
275            key: Storage key of the entry to delete. Must be a non-empty string.
276
277        Returns:
278            Empty response body. HTTP 204 No Content on success.
279        """
280        self._http.request(f"/api/v1/kv/{key}", method="DELETE")
281
282    def get(self, key: str, *, user: str | None = None) -> KeyValueStorageEntry:
283        """
284        Retrieve a key-value storage entry
285        Returns the key-value storage entry identified by `key` for the target user.
286        Returns 404 if no entry exists for that key.
287        End-user (user-JWT) callers retrieve entries from their own storage. Developer
288        and server-to-server callers must supply a `user` param identifying the target
289        user within their app's scope.
290
291        Args:
292            key: Storage key of the entry to retrieve. Must be a non-empty string.
293            user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
294
295        Returns:
296            The key-value storage entry for the given key.
297        """
298        query: dict[str, object] = {}
299        if user is not None:
300            query["user"] = user
301        return self._http.request(
302            f"/api/v1/kv/{key}",
303            query=query,
304            response_type=KeyValueStorageEntry,
305        )
306
307    def upsert(self, key: str, input: KvUpsertInput) -> KeyValueStorageEntry:
308        """
309        Create or update a key-value storage entry
310        Creates a new key-value storage entry for the given `key`, or overwrites the
311        value if an entry already exists. This is the idempotent alternative to the
312        create endpoint: safe to call regardless of whether the key already exists.
313        End-user (user-JWT) callers always write to their own storage. Developer and
314        server-to-server callers must supply a `user` param identifying the target user
315        within their app's scope. Attempting to write for a user in a different app
316        returns 404.
317
318        Args:
319            key: Storage key to create or overwrite. Must be a non-empty string.
320            input: Request body.
321            input.user: Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.
322            input.value: New value to store under `key`. Must be a non-empty string. Replaces any existing value.
323
324        Returns:
325            The created or updated key-value storage entry.
326        """
327        return self._http.request(
328            f"/api/v1/kv/{key}",
329            method="PUT",
330            body=input,
331            response_type=KeyValueStorageEntry,
332        )