archastro.platform.v1.resources.files

  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: 03df018ed706
  4
  5from __future__ import annotations
  6
  7from typing import Any, Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import StorageFile
 11
 12
 13class FileCreateInputAclAddItem(TypedDict, total=False):
 14    actions: Required[list[str]]
 15    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 16    principal: str | None
 17    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 18    principal_type: Required[str]
 19    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 20
 21
 22class FileCreateInputAclGrantsItem(TypedDict, total=False):
 23    actions: Required[list[str]]
 24    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 25    principal: str | None
 26    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 27    principal_type: Required[str]
 28    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 29
 30
 31class FileCreateInputAclRemoveItem(TypedDict, total=False):
 32    principal: str | None
 33    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
 34    principal_type: Required[str]
 35    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 36
 37
 38class FileCreateInputAcl(TypedDict, total=False):
 39    add: list[FileCreateInputAclAddItem] | None
 40    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
 41    grants: list[FileCreateInputAclGrantsItem] | None
 42    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
 43    remove: list[FileCreateInputAclRemoveItem] | None
 44    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
 45
 46
 47class FileCreateInput(TypedDict, total=False):
 48    "Upload a file"
 49
 50    acl: FileCreateInputAcl | None
 51    "Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone."
 52    agent: str | None
 53    "Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent."
 54    content_type: Required[str]
 55    'MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.'
 56    data: Required[str]
 57    "Base64-encoded binary content of the file to upload."
 58    filename: Required[str]
 59    'Original filename including extension, e.g. `"avatar.png"`.'
 60    org: str | None
 61    "Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted."
 62    share: bool | None
 63    "When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared."
 64    team: str | None
 65    "Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided."
 66    user: str | None
 67    "User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified."
 68
 69
 70class FileUpdateInput(TypedDict, total=False):
 71    "Update a file"
 72
 73    filename: str | None
 74    'New name for the file, including extension, e.g. `"report_v2.pdf"`. Omit to leave the current filename unchanged.'
 75    provider_metadata: dict[str, Any] | None
 76    "Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged."
 77    share: bool | None
 78    "Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged."
 79
 80
 81class AsyncFileResource:
 82    def __init__(self, http: HttpClient):
 83        self._http = http
 84
 85    async def create(self, input: FileCreateInput) -> StorageFile:
 86        """
 87        Upload a file
 88        Creates a new file from base64-encoded content and returns the resulting file object,
 89        including a signed download URL. Use this endpoint to store images, documents, or
 90        other binary assets that can then be referenced by agents, teams, or users.
 91        App scope is derived from the authenticated viewer's bearer token or publishable key.
 92        You may optionally associate the file with an organization, team, user, or agent by
 93        passing the corresponding ID. If no owner is specified and the viewer is a user, the
 94        file is automatically attributed to that user.
 95        Pass `share: true` to additionally mint a stable public URL for the file
 96        (returned as `share_url`), fetchable by anyone without authentication for
 97        example to embed an uploaded image in a GitHub PR body or other external
 98        markdown. The URL does not expire. Sharing is revoked by setting
 99        `share: false` on `PATCH /api/v1/files/:file` with the same credential
100        (or `archastro update file <id> --unshare`); re-enabling sharing
101        reactivates previously issued URLs. Only image content types can be
102        shared.
103        Returns `422` when the `data` field is not valid base64, the changeset is
104        invalid, or `share` is requested for a non-image content type.
105        Returns `403` when the request lacks the required app scope.
106
107        Args:
108            input: Request body.
109            input.acl: Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
110            input.agent: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
111            input.content_type: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
112            input.data: Base64-encoded binary content of the file to upload.
113            input.filename: Original filename including extension, e.g. `"avatar.png"`.
114            input.org: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
115            input.share: When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared.
116            input.team: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
117            input.user: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
118
119        Returns:
120            The newly created file, including a signed download URL.
121        """
122        return await self._http.request(
123            "/api/v1/files",
124            method="POST",
125            body=input,
126            response_type=StorageFile,
127        )
128
129    async def update(self, file: str, input: FileUpdateInput) -> StorageFile:
130        """
131        Update a file
132        Updates mutable fields of an existing file. Only the fields you supply are
133        changed; omitted fields retain their current values. The file's stored content
134        and `content_type` cannot be changed after creation.
135        This endpoint is the companion to `share: true` on file upload: the same
136        credential that granted public sharing can revoke it here with `share: false`
137        (or grant it later with `share: true`; only image content types can be
138        shared, and re-enabling sharing reactivates any previously issued share
139        URLs). App scope is derived from the authenticated viewer, matching upload.
140        A file that exists but is not visible to the current viewer returns `404`
141        rather than `403` to avoid revealing the file's existence.
142
143        Args:
144            file: File ID (`fil_...`) of the file to update.
145            input: Request body.
146            input.filename: New name for the file, including extension, e.g. `"report_v2.pdf"`. Omit to leave the current filename unchanged.
147            input.provider_metadata: Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged.
148            input.share: Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged.
149
150        Returns:
151            The updated file, including a signed download URL.
152        """
153        return await self._http.request(
154            f"/api/v1/files/{file}",
155            method="PATCH",
156            body=input,
157            response_type=StorageFile,
158        )
159
160    async def avatar(self, file: str, token: str) -> dict[str, str]:
161        """
162        Fetch an agent avatar image
163        Returns the raw image bytes for an agent's profile picture identified by `file`.
164        This endpoint is designed for integration partners (such as Slack) that fetch
165        avatar URLs via plain GET requests without bearer token support. Authorization
166        is performed via a short, stable capability `token` rather than an HTTP header.
167        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
168        but it is invalidated when the agent's profile picture is replaced or the agent is
169        deleted shared caches may continue serving the old image until the
170        `Cache-Control` max-age of one hour elapses. The endpoint never redirects to
171        a signed storage URL; bytes are served inline so behavior is consistent across
172        storage backends.
173        All failure modes invalid file ID, invalid token, file not currently referenced
174        as an agent avatar return a uniform `404` to avoid acting as an existence oracle.
175
176        Args:
177            file: File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
178            token: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
179
180        Returns:
181            Raw image bytes of the agent avatar, served with the file's original content type.
182        """
183        query: dict[str, object] = {}
184        query["token"] = token
185        return await self._http.request_raw(f"/api/v1/files/{file}/avatar", query=query)
186
187    async def org_logo(self, file: str, token: str) -> dict[str, str]:
188        """
189        Fetch an org logo image
190        Returns the raw image bytes for an organization's logo identified by `file`.
191        This endpoint backs the `org_logo.url` field of catalog payloads (such as
192        `GET /api/v1/solutions`), which anonymous consumers the public marketplace's
193        page cache, OpenGraph scrapers may hold far longer than a signed storage URL
194        lives. Authorization is performed via a short, stable capability `token` rather
195        than an HTTP header, so the URL never expires.
196        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
197        but it is invalidated when the org's logo is replaced or removed shared caches
198        may continue serving the old image until the `Cache-Control` max-age of one hour
199        elapses. The endpoint never redirects to a signed storage URL; bytes are served
200        inline so behavior is consistent across storage backends.
201        All failure modes invalid file ID, invalid token, file not currently referenced
202        as an org logo return a uniform `404` to avoid acting as an existence oracle.
203
204        Args:
205            file: File ID of the org's logo (`fil_...`). Must be currently set as an organization's logo within the same app.
206            token: HMAC capability token authorizing access to this specific file. Obtained from the `org_logo.url` minted when the logo was serialized.
207
208        Returns:
209            Raw image bytes of the org logo, served with the file's original content type.
210        """
211        query: dict[str, object] = {}
212        query["token"] = token
213        return await self._http.request_raw(f"/api/v1/files/{file}/org_logo", query=query)
214
215    async def share(self, file: str, token: str) -> dict[str, str]:
216        """
217        Fetch a publicly shared file
218        Returns the raw image bytes for a file that was explicitly shared for public
219        access, identified by `file`. This endpoint is designed for consumers that hold
220        a URL far longer than a signed storage URL lives GitHub PR bodies (whose camo
221        image proxy re-fetches from the origin URL), wikis, and issue trackers and
222        fetch it via plain GET requests without bearer token support. Authorization is
223        performed via a short, stable capability `token` rather than an HTTP header.
224        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
225        but it is invalidated when sharing is turned off for the file (`share: false` on
226        the file update endpoint) or the file is deleted shared caches may continue
227        serving the bytes until the `Cache-Control` max-age of one hour elapses. The
228        endpoint never redirects to a signed storage URL; bytes are served inline so
229        behavior is consistent across storage backends. Only image content types are
230        served.
231        All failure modes invalid file ID, invalid token, file not currently shared
232        return a uniform `404` to avoid acting as an existence oracle.
233
234        Args:
235            file: File ID of the shared file (`fil_...`). The file must currently be marked as publicly shared.
236            token: HMAC capability token authorizing access to this specific file. Obtained from the `share_url` returned when the file was uploaded with `share: true`.
237
238        Returns:
239            Raw image bytes of the shared file, served with the file's original content type.
240        """
241        query: dict[str, object] = {}
242        query["token"] = token
243        return await self._http.request_raw(f"/api/v1/files/{file}/share", query=query)
244
245
246class FileResource:
247    def __init__(self, http: SyncHttpClient):
248        self._http = http
249
250    def create(self, input: FileCreateInput) -> StorageFile:
251        """
252        Upload a file
253        Creates a new file from base64-encoded content and returns the resulting file object,
254        including a signed download URL. Use this endpoint to store images, documents, or
255        other binary assets that can then be referenced by agents, teams, or users.
256        App scope is derived from the authenticated viewer's bearer token or publishable key.
257        You may optionally associate the file with an organization, team, user, or agent by
258        passing the corresponding ID. If no owner is specified and the viewer is a user, the
259        file is automatically attributed to that user.
260        Pass `share: true` to additionally mint a stable public URL for the file
261        (returned as `share_url`), fetchable by anyone without authentication for
262        example to embed an uploaded image in a GitHub PR body or other external
263        markdown. The URL does not expire. Sharing is revoked by setting
264        `share: false` on `PATCH /api/v1/files/:file` with the same credential
265        (or `archastro update file <id> --unshare`); re-enabling sharing
266        reactivates previously issued URLs. Only image content types can be
267        shared.
268        Returns `422` when the `data` field is not valid base64, the changeset is
269        invalid, or `share` is requested for a non-image content type.
270        Returns `403` when the request lacks the required app scope.
271
272        Args:
273            input: Request body.
274            input.acl: Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
275            input.agent: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
276            input.content_type: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
277            input.data: Base64-encoded binary content of the file to upload.
278            input.filename: Original filename including extension, e.g. `"avatar.png"`.
279            input.org: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
280            input.share: When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared.
281            input.team: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
282            input.user: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
283
284        Returns:
285            The newly created file, including a signed download URL.
286        """
287        return self._http.request(
288            "/api/v1/files",
289            method="POST",
290            body=input,
291            response_type=StorageFile,
292        )
293
294    def update(self, file: str, input: FileUpdateInput) -> StorageFile:
295        """
296        Update a file
297        Updates mutable fields of an existing file. Only the fields you supply are
298        changed; omitted fields retain their current values. The file's stored content
299        and `content_type` cannot be changed after creation.
300        This endpoint is the companion to `share: true` on file upload: the same
301        credential that granted public sharing can revoke it here with `share: false`
302        (or grant it later with `share: true`; only image content types can be
303        shared, and re-enabling sharing reactivates any previously issued share
304        URLs). App scope is derived from the authenticated viewer, matching upload.
305        A file that exists but is not visible to the current viewer returns `404`
306        rather than `403` to avoid revealing the file's existence.
307
308        Args:
309            file: File ID (`fil_...`) of the file to update.
310            input: Request body.
311            input.filename: New name for the file, including extension, e.g. `"report_v2.pdf"`. Omit to leave the current filename unchanged.
312            input.provider_metadata: Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged.
313            input.share: Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged.
314
315        Returns:
316            The updated file, including a signed download URL.
317        """
318        return self._http.request(
319            f"/api/v1/files/{file}",
320            method="PATCH",
321            body=input,
322            response_type=StorageFile,
323        )
324
325    def avatar(self, file: str, token: str) -> dict[str, str]:
326        """
327        Fetch an agent avatar image
328        Returns the raw image bytes for an agent's profile picture identified by `file`.
329        This endpoint is designed for integration partners (such as Slack) that fetch
330        avatar URLs via plain GET requests without bearer token support. Authorization
331        is performed via a short, stable capability `token` rather than an HTTP header.
332        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
333        but it is invalidated when the agent's profile picture is replaced or the agent is
334        deleted shared caches may continue serving the old image until the
335        `Cache-Control` max-age of one hour elapses. The endpoint never redirects to
336        a signed storage URL; bytes are served inline so behavior is consistent across
337        storage backends.
338        All failure modes invalid file ID, invalid token, file not currently referenced
339        as an agent avatar return a uniform `404` to avoid acting as an existence oracle.
340
341        Args:
342            file: File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
343            token: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
344
345        Returns:
346            Raw image bytes of the agent avatar, served with the file's original content type.
347        """
348        query: dict[str, object] = {}
349        query["token"] = token
350        return self._http.request_raw(f"/api/v1/files/{file}/avatar", query=query)
351
352    def org_logo(self, file: str, token: str) -> dict[str, str]:
353        """
354        Fetch an org logo image
355        Returns the raw image bytes for an organization's logo identified by `file`.
356        This endpoint backs the `org_logo.url` field of catalog payloads (such as
357        `GET /api/v1/solutions`), which anonymous consumers the public marketplace's
358        page cache, OpenGraph scrapers may hold far longer than a signed storage URL
359        lives. Authorization is performed via a short, stable capability `token` rather
360        than an HTTP header, so the URL never expires.
361        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
362        but it is invalidated when the org's logo is replaced or removed shared caches
363        may continue serving the old image until the `Cache-Control` max-age of one hour
364        elapses. The endpoint never redirects to a signed storage URL; bytes are served
365        inline so behavior is consistent across storage backends.
366        All failure modes invalid file ID, invalid token, file not currently referenced
367        as an org logo return a uniform `404` to avoid acting as an existence oracle.
368
369        Args:
370            file: File ID of the org's logo (`fil_...`). Must be currently set as an organization's logo within the same app.
371            token: HMAC capability token authorizing access to this specific file. Obtained from the `org_logo.url` minted when the logo was serialized.
372
373        Returns:
374            Raw image bytes of the org logo, served with the file's original content type.
375        """
376        query: dict[str, object] = {}
377        query["token"] = token
378        return self._http.request_raw(f"/api/v1/files/{file}/org_logo", query=query)
379
380    def share(self, file: str, token: str) -> dict[str, str]:
381        """
382        Fetch a publicly shared file
383        Returns the raw image bytes for a file that was explicitly shared for public
384        access, identified by `file`. This endpoint is designed for consumers that hold
385        a URL far longer than a signed storage URL lives GitHub PR bodies (whose camo
386        image proxy re-fetches from the origin URL), wikis, and issue trackers and
387        fetch it via plain GET requests without bearer token support. Authorization is
388        performed via a short, stable capability `token` rather than an HTTP header.
389        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
390        but it is invalidated when sharing is turned off for the file (`share: false` on
391        the file update endpoint) or the file is deleted shared caches may continue
392        serving the bytes until the `Cache-Control` max-age of one hour elapses. The
393        endpoint never redirects to a signed storage URL; bytes are served inline so
394        behavior is consistent across storage backends. Only image content types are
395        served.
396        All failure modes invalid file ID, invalid token, file not currently shared
397        return a uniform `404` to avoid acting as an existence oracle.
398
399        Args:
400            file: File ID of the shared file (`fil_...`). The file must currently be marked as publicly shared.
401            token: HMAC capability token authorizing access to this specific file. Obtained from the `share_url` returned when the file was uploaded with `share: true`.
402
403        Returns:
404            Raw image bytes of the shared file, served with the file's original content type.
405        """
406        query: dict[str, object] = {}
407        query["token"] = token
408        return self._http.request_raw(f"/api/v1/files/{file}/share", query=query)