@nohead/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ Changes to `@nohead/sdk` that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.2.0
+
+- `onRetry` client option: called before each retry with the attempt, the
+  delay, and the status or error that failed, for example to report retries.
+- `assets.upload()` with an `idempotencyKey` no longer fails when it
+  completes the upload: the key only starts it. Running the same upload again
+  resumes it, and returns an asset that is already `ready` without sending the
+  bytes again.
+- Types follow the API's current contract. They add types only for
+  operations an API key can't call, so no method changed.
+
 ## 0.1.0
 
 The first release.

package/README.md

@@ -14,7 +14,7 @@ for await (const post of nohead.records.list("posts", {
 }
 ```
 
-> **Status:** 0.x, not yet published to npm. Until it is, install from GitHub: `npm install github:nohead-io/nohead-typescript`.
+> **Status:** 0.x until the Nohead API launches.
 
 ## Contents
 
@@ -50,16 +50,17 @@ const nohead = new Nohead({
 })
 ```
 
-| Option       | Default                                        |                                                      |
-| ------------ | ---------------------------------------------- | ---------------------------------------------------- |
-| `apiKey`     | `NOHEAD_API_KEY`                               | A project API key (`sk_live_…`). Required.           |
-| `baseUrl`    | `NOHEAD_API_URL`, else `https://api.nohead.io` |                                                      |
-| `projectId`  | the key's project                              | Looked up once with `GET /v1/me` when omitted.       |
-| `maxRetries` | `2`                                            | See [retries](#retries-and-idempotency).             |
-| `timeout`    | `60000`                                        | Milliseconds per attempt.                            |
-| `fetch`      | `globalThis.fetch`                             | For proxies, instrumentation and tests.              |
-| `headers`    | `{}`                                           | Added to every request.                              |
-| `warnings`   | `true`                                         | Logs deprecation and plan usage warnings, once each. |
+| Option       | Default                                        |                                                                    |
+| ------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
+| `apiKey`     | `NOHEAD_API_KEY`                               | A project API key (`sk_live_…`). Required.                         |
+| `baseUrl`    | `NOHEAD_API_URL`, else `https://api.nohead.io` |                                                                    |
+| `projectId`  | the key's project                              | Looked up once with `GET /v1/me` when omitted.                     |
+| `maxRetries` | `2`                                            | See [retries](#retries-and-idempotency).                           |
+| `timeout`    | `60000`                                        | Milliseconds per attempt.                                          |
+| `fetch`      | `globalThis.fetch`                             | For proxies, instrumentation and tests.                            |
+| `headers`    | `{}`                                           | Added to every request.                                            |
+| `warnings`   | `true`                                         | Logs deprecation and plan usage warnings, once each.               |
+| `onRetry`    |                                                | Called before each retry. See [retries](#retries-and-idempotency). |
 
 API keys belong to a project, so methods like `collections.list()` need no project ID. Collections can be named by ID or slug everywhere.
 
@@ -163,6 +164,17 @@ Failed requests are retried twice by default (`maxRetries`), with exponential ba
 - what's retried: connection errors, timeouts, 429, 500, 502, 503, 504, and a 409 for a request that is still running
 - `Retry-After` is honored up to 60 seconds; a longer one throws `RateLimitError` straight away
 
+To report retries, pass `onRetry`. It gets the retry's `attempt` (1 for the first), `delay` in seconds, `url`, the failed `status` (none when the connection failed) and the `error`:
+
+```ts
+const nohead = new Nohead({
+  onRetry: ({ attempt, delay, status }) =>
+    console.error(
+      `Retry ${attempt} in ${delay.toFixed(1)}s (${status ?? "network"})`
+    ),
+})
+```
+
 Every write gets an `Idempotency-Key` that stays the same across its retries, so a retry after a lost response never writes twice. To make a write safe across your own retries (a job that may run twice), pass a key:
 
 ```ts
@@ -223,6 +235,8 @@ const { url } = await nohead.assets.imageUrl(asset.id, {
 
 **Errors:** `UploadError` if storage refuses the bytes; `ValidationError` if the file fails the checks.
 
+**Resuming:** pass an `idempotencyKey` (`upload(file, {}, { idempotencyKey })`) and running the same upload again picks up where it stopped. An asset that is already `ready` comes back without sending the bytes again.
+
 **Uploading from a browser:** create the upload on your server with `createUpload`, `PUT` the file from the browser, then `complete` it.
 
 ## Search
@@ -336,7 +350,7 @@ NOHEAD_API_URL=http://localhost:3000 NOHEAD_API_KEY=sk_live_… npm run smoke
   - the types, in `src/generated/types.gen.ts` (hey-api)
   - the operation table, in `src/generated/operations.gen.ts`
 - The methods in `src/resources` are written by hand.
-- `test/contract.test.ts` calls every public method. It fails when an API-key operation in the contract has no method, or when a request doesn't match its operation.
+- `test/contract.test.ts` calls every public method. It fails when an API-key operation in the contract has no method, when a query parameter is never sent (no method takes it, or no call passes it), or when a request doesn't match its operation.
 
 The smoke test (`smoke/smoke.ts`) runs the core flow against a real API, using the built package. Nohead's own CI runs it on every API contract change.
 
@@ -344,9 +358,9 @@ The smoke test (`smoke/smoke.ts`) runs the core flow against a real API, using t
 
 1. Bump the version in `package.json` and `src/version.ts`.
 2. Add a section for it to `CHANGELOG.md` (`## 1.2.3`), which becomes the release's notes.
-3. Merge to `main`.
-4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`.
-5. The tag starts `.github/workflows/release.yml`. It checks the version and its notes, tests, and stages the package on npm with provenance through trusted publishing (no token). Then it creates a draft GitHub release.
+3. Merge to `main`. Its ruleset requires the **CI passed** check, so the commit goes through a pull request or a branch whose CI passed, and force pushes are refused.
+4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. Nobody else can push `v*` tags: a tag ruleset lets only that workflow's deploy key through.
+5. The tag starts `.github/workflows/release.yml`. Its publishing job runs in the `release` environment, which only `v*` tags can use, and the registry's trusted publisher accepts only that environment. It checks the version and its notes, tests, and stages the package on npm with provenance through trusted publishing (no token). Then it creates a draft GitHub release.
 6. Approve the staged version with 2FA, on npmjs.com, or with `npm stage list @nohead/sdk` and `npm stage approve <stage-id>`. Only then is it installable. Publish the draft GitHub release.
 
 ## License

package/dist/core.d.ts

@@ -1,4 +1,5 @@
 import { APIPromise, PagePromise } from "./api-promise.ts";
+import { NoheadError } from "./errors.ts";
 import { type OperationId, type Operations } from "./generated/operations.gen.ts";
 import type { ListMeta } from "./generated/types.gen.ts";
 export declare const DEFAULT_BASE_URL = "https://api.nohead.io";
@@ -19,6 +20,21 @@ export interface ClientOptions {
     headers?: Record<string, string>;
     /** Log deprecation and plan usage warnings (once each). Default true. */
     warnings?: boolean;
+    /** Called before each retry, for example to report it. */
+    onRetry?: (retry: RetryEvent) => void;
+}
+/** A retry about to happen (`onRetry`). */
+export interface RetryEvent {
+    /** 1 for the first retry of the request, 2 for the second… */
+    attempt: number;
+    /** Seconds the client waits before it. */
+    delay: number;
+    /** The URL being retried. */
+    url: string;
+    /** The status that failed, or undefined when the connection did. */
+    status?: number;
+    /** What failed: an `APIError` or a `ConnectionError` (none for storage). */
+    error?: NoheadError;
 }
 export interface RequestOptions {
     /** Sent as `Idempotency-Key` on writes. Generated when omitted. */

package/dist/core.js

@@ -15,6 +15,7 @@ export class Core {
     #maxRetries;
     #timeout;
     #warnings;
+    #onRetry;
     #projectId;
     constructor(options) {
         const env = environment();
@@ -31,6 +32,7 @@ export class Core {
         this.#maxRetries = options.maxRetries ?? 2;
         this.#timeout = options.timeout ?? 60_000;
         this.#warnings = options.warnings ?? true;
+        this.#onRetry = options.onRetry;
         if (options.projectId)
             this.#projectId = Promise.resolve(options.projectId);
     }
@@ -68,18 +70,21 @@ export class Core {
             ? (options.maxRetries ?? this.#maxRetries)
             : 0;
         for (let attempt = 0;; attempt++) {
+            let failed;
             try {
                 const { response } = await this.#attempt(url, init, options, false);
                 if (!RETRYABLE_STATUSES.has(response.status) || attempt >= maxRetries) {
                     return response;
                 }
+                failed = { status: response.status };
             }
             catch (error) {
                 if (!(error instanceof ConnectionError) || attempt >= maxRetries) {
                     throw error;
                 }
+                failed = { error };
             }
-            await sleep(backoff(attempt), options.signal);
+            await this.#retry(url, attempt, backoff(attempt), failed, options.signal);
         }
     }
     async #send(operation, input, options) {
@@ -122,7 +127,7 @@ export class Core {
                 if (!(error instanceof ConnectionError) || attempt >= maxRetries) {
                     throw error;
                 }
-                await sleep(backoff(attempt), options.signal);
+                await this.#retry(url.toString(), attempt, backoff(attempt), { error }, options.signal);
                 continue;
             }
             const { response, body } = result;
@@ -134,9 +139,13 @@ export class Core {
             const delay = retryDelay(error, attempt, maxRetries);
             if (delay === undefined)
                 throw error;
-            await sleep(delay, options.signal);
+            await this.#retry(url.toString(), attempt, delay, { status: response.status, error }, options.signal);
         }
     }
+    #retry(url, attempt, delay, failed, signal) {
+        this.#onRetry?.({ attempt: attempt + 1, delay, url, ...failed });
+        return sleep(delay, signal);
+    }
     async #attempt(url, init, options, readBody) {
         const timeout = options.timeout ?? this.#timeout;
         const timer = AbortSignal.timeout(timeout);

package/dist/generated/schemas.gen.d.ts

@@ -1 +1 @@
-export type { AccessReview, Actor, ApiKey, ApiKeyCreate, ApiKeyList, ApiKeyProperties, ApiKeyScope, ApiKeyWithToken, Asset, AssetList, AssetUpload, AssetUploadCreate, AuditEvent, AuditEventList, Billing, BillingCheckout, BillingPlan, BillingPortal, BillingSession, BillingSubscription, BulkRecordsRequest, BulkRecordsResult, Change, ChangeVia, Collection, CollectionCreate, CollectionList, CollectionUpdate, DownloadUrl, Error, ErrorDetail, ErrorType, FeatureFlags, Field, FieldCreate, FieldDefinition, FieldList, FieldMigration, FieldMigrationCounts, FieldMigrationList, FieldMigrationPreview, FieldMigrationRequest, FieldType, FieldUpdate, Health, ImageUrl, Invitation, InvitationCreate, InvitationList, ListMeta, MeUpdate, Membership, MembershipList, MembershipUpdate, NullableTimestamp, Organization, OrganizationCreate, OrganizationList, OrganizationUpdate, Permission, Principal, Project, ProjectCreate, ProjectList, ProjectUpdate, PublishedOnly, RecordCount, RecordData, RecordDiff, RecordList, RecordRevision, RecordRevisionDetail, RecordRevisionList, RecordRevisionProperties, RecordSchedule, RecordScheduleUpdate, RecordWrite, Redaction, RequestId, RevertPreview, Role, Schema, SchemaChange, SchemaChangeDetail, SchemaChangeList, SchemaChangeProperties, SchemaDefinition, SearchIndex, SearchResults, Timestamp, Usage, UsageMetric, Via, Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryList, WebhookDeliveryProperties, WebhookEventPayload, WebhookEventType, WebhookList, WebhookProperties, WebhookUpdate, WebhookWithSecret, } from "./types.gen.ts";
+export type { AccessReview, AccountDeletion, AccountDeletionCode, Actor, ApiKey, ApiKeyCreate, ApiKeyList, ApiKeyProperties, ApiKeyScope, ApiKeyWithToken, Asset, AssetList, AssetUpload, AssetUploadCreate, AuditEvent, AuditEventList, Billing, BillingCheckout, BillingPlan, BillingPortal, BillingSession, BillingSubscription, BulkRecordsRequest, BulkRecordsResult, Change, ChangeVia, Collection, CollectionCreate, CollectionList, CollectionUpdate, DownloadUrl, Error, ErrorDetail, ErrorType, FeatureFlags, Field, FieldCreate, FieldDefinition, FieldList, FieldMigration, FieldMigrationCounts, FieldMigrationList, FieldMigrationPreview, FieldMigrationRequest, FieldType, FieldUpdate, Health, ImageUrl, Invitation, InvitationCreate, InvitationList, ListMeta, MeUpdate, Membership, MembershipList, MembershipUpdate, NullableTimestamp, Organization, OrganizationCreate, OrganizationList, OrganizationUpdate, Permission, Principal, Project, ProjectCreate, ProjectList, ProjectUpdate, PublishedOnly, RecordCount, RecordData, RecordDiff, RecordList, RecordRevision, RecordRevisionDetail, RecordRevisionList, RecordRevisionProperties, RecordSchedule, RecordScheduleUpdate, RecordWrite, Redaction, RequestId, RevertPreview, Role, Schema, SchemaChange, SchemaChangeDetail, SchemaChangeList, SchemaChangeProperties, SchemaDefinition, SearchIndex, SearchResults, Timestamp, Usage, UsageMetric, UsageRetention, UsageRetentionGrace, Via, Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryList, WebhookDeliveryProperties, WebhookEventPayload, WebhookEventType, WebhookList, WebhookProperties, WebhookUpdate, WebhookWithSecret, } from "./types.gen.ts";

package/dist/generated/types.gen.d.ts

@@ -93,7 +93,7 @@ export type Invitation = {
         name: string;
     };
     /**
-     * What became of the invitation email, or null while it has not been sent (or when sending is off). `sent`: accepted for delivery. `not_sent`: the address had bounced or been marked as spam before, so no email went out. `bounced`: the email could not be delivered; check the address. `complained`: the invitee marked it as spam. Either way the invitation still works when the invitee signs in with the address.
+     * What became of the invitation email, or null while it has not been sent (or when sending is off). `sent`: accepted for delivery. `not_sent`: no email went out, because the address had bounced or been marked as spam before, or had already received several invitation emails that day. `bounced`: the email could not be delivered; check the address. `complained`: the invitee marked it as spam. Either way the invitation still works when the invitee signs in with the address.
      */
     email_delivery: null | {
         status: 'sent' | 'not_sent' | 'bounced' | 'complained';
@@ -186,10 +186,15 @@ export type Field = {
     api_key: string;
     type: FieldType;
     required: boolean;
+    /**
+     * A list of distinct values (a repeated value is refused with `duplicate_value`). Not available for boolean, rich_text and json fields.
+     */
     multiple: boolean;
     position: number;
     /**
-     * Type-specific options, e.g. `max_length`, `options`, `target_collection_id`, plus
+     * Type-specific options, e.g. `max_length`, `options`, `target_collection_id`,
+     * `accepted_types` (asset fields: MIME types or `type*` wildcards that newly
+     * written values must have; any file when absent), plus
      * the options for searches with API keys: `searchable` (the search words match the
      * field; default true for text, long_text, rich_text and enum), `filterable` and
      * `sortable` (default false).
@@ -223,6 +228,9 @@ export type FieldCreate = {
     api_key: string;
     type: FieldType;
     required?: boolean;
+    /**
+     * A list of distinct values (a repeated value is refused with `duplicate_value`). Not available for boolean, rich_text and json fields.
+     */
     multiple?: boolean;
     position?: number;
     configuration?: {
@@ -234,6 +242,9 @@ export type FieldUpdate = {
     api_key?: string;
     type?: FieldType;
     required?: boolean;
+    /**
+     * A list of distinct values (a repeated value is refused with `duplicate_value`). Not available for boolean, rich_text and json fields.
+     */
     multiple?: boolean;
     position?: number;
     configuration?: {
@@ -319,6 +330,12 @@ export type Actor = {
      * The user (`usr_...`) or API key (`key_...`), or null for system changes.
      */
     id: string | null;
+    /**
+     * Resolved when read, never stored: a user's current name (or
+     * email), "Deleted user" once they deleted their account, an API
+     * key's name, or "System".
+     *
+     */
     name: string | null;
 };
 export type SchemaChange = SchemaChangeProperties;
@@ -355,6 +372,9 @@ export type FieldDefinition = {
     configuration: {
         [key: string]: unknown;
     };
+    /**
+     * A list of distinct values (a repeated value is refused with `duplicate_value`). Not available for boolean, rich_text and json fields.
+     */
     multiple: boolean;
     required: boolean;
 };
@@ -369,6 +389,9 @@ export type FieldMigrationRequest = {
     configuration?: {
         [key: string]: unknown;
     };
+    /**
+     * A list of distinct values (a repeated value is refused with `duplicate_value`). Not available for boolean, rich_text and json fields.
+     */
     multiple?: boolean;
     required?: boolean;
     /**
@@ -629,6 +652,22 @@ export type FeatureFlags = {
         [key: string]: boolean;
     };
 };
+export type AccountDeletionCode = {
+    object: 'account_deletion_code';
+    /**
+     * Where the code was sent.
+     */
+    email: string;
+    expires_at: string;
+};
+export type AccountDeletion = {
+    object: 'account_deletion';
+    /**
+     * The deleted user, as history still refers to it.
+     */
+    user_id: string;
+    deleted_at: string;
+};
 export type Principal = {
     object: 'principal';
     type: 'user' | 'api_key';
@@ -828,6 +867,29 @@ export type Usage = {
         end: string;
     };
     metrics: Array<UsageMetric>;
+    retention: UsageRetention;
+};
+/**
+ * How long the plan keeps record revisions (beyond each record's first and latest 10) and audit events, in days; null keeps everything.
+ */
+export type UsageRetention = {
+    revision_days: number | null;
+    audit_days: number | null;
+    /**
+     * After a downgrade, the previous plan's longer retention still applies for 30 days; history past the plan's retention is removed after `ends_at`. Null otherwise.
+     */
+    grace: null | UsageRetentionGrace;
+};
+export type UsageRetentionGrace = {
+    ends_at: string;
+    /**
+     * Days of revisions kept until `ends_at`; null keeps everything.
+     */
+    revision_days: number | null;
+    /**
+     * Days of audit events kept until `ends_at`.
+     */
+    audit_days: number | null;
 };
 export type UsageMetric = {
     metric: 'api_requests' | 'search_requests' | 'image_transformations' | 'asset_uploads' | 'asset_downloads' | 'webhook_deliveries' | 'record_revisions' | 'projects' | 'collections' | 'records' | 'members' | 'webhooks' | 'asset_storage_bytes' | 'indexed_records';
@@ -3607,6 +3669,10 @@ export type AssetsListData = {
          * List soft-deleted items instead of active ones.
          */
         deleted?: boolean;
+        /**
+         * Comma-separated MIME types or `type*` wildcards.
+         */
+        content_type?: string;
     };
     url: '/v1/projects/{project_id}/assets';
 };
@@ -3680,6 +3746,12 @@ export type AssetsUploadErrors = {
      * Authentication is missing or invalid.
      */
     401: Error;
+    /**
+     * The change would exceed a hard limit of the organization's plan. The
+     * detail names the metric (`field`) with its `usage` and `limit`.
+     *
+     */
+    402: Error;
     /**
      * The caller is not allowed to perform this action.
      */
@@ -6671,6 +6743,66 @@ export type HealthCheckResponses = {
     200: Health;
 };
 export type HealthCheckResponse = HealthCheckResponses[keyof HealthCheckResponses];
+export type MeDeleteData = {
+    body: {
+        /**
+         * The six-digit code emailed by `POST /v1/me/deletion-code`.
+         */
+        code: string;
+    };
+    headers?: {
+        /**
+         * A unique value (1-255 printable ASCII characters) that makes retrying
+         * this request safe. The first response (below 500) is stored for 24
+         * hours per user or API key; retries with the same key and the same
+         * request get it again with an `Idempotent-Replayed: true` header. The
+         * same key with a different request is refused with `400`; a retry while
+         * the first request is still running gets `409`.
+         *
+         */
+        'Idempotency-Key'?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/me';
+};
+export type MeDeleteErrors = {
+    /**
+     * The request was malformed.
+     */
+    400: Error;
+    /**
+     * Authentication is missing or invalid.
+     */
+    401: Error;
+    /**
+     * The caller is not allowed to perform this action.
+     */
+    403: Error;
+    /**
+     * The request conflicts with current state.
+     */
+    409: Error;
+    /**
+     * The request failed validation.
+     */
+    422: Error;
+    /**
+     * Too many requests for this API key or user (or, with failing
+     * credentials, this IP address). Wait `Retry-After` seconds; retries with
+     * the same `Idempotency-Key` are safe.
+     *
+     */
+    429: Error;
+};
+export type MeDeleteError = MeDeleteErrors[keyof MeDeleteErrors];
+export type MeDeleteResponses = {
+    /**
+     * The account is deleted, and the session cookie cleared.
+     */
+    200: AccountDeletion;
+};
+export type MeDeleteResponse = MeDeleteResponses[keyof MeDeleteResponses];
 export type MeGetData = {
     body?: never;
     path?: never;
@@ -6753,6 +6885,57 @@ export type MeUpdateResponses = {
     200: Principal;
 };
 export type MeUpdateResponse = MeUpdateResponses[keyof MeUpdateResponses];
+export type MeDeletionCodeSendData = {
+    body?: never;
+    headers?: {
+        /**
+         * A unique value (1-255 printable ASCII characters) that makes retrying
+         * this request safe. The first response (below 500) is stored for 24
+         * hours per user or API key; retries with the same key and the same
+         * request get it again with an `Idempotent-Replayed: true` header. The
+         * same key with a different request is refused with `400`; a retry while
+         * the first request is still running gets `409`.
+         *
+         */
+        'Idempotency-Key'?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/me/deletion-code';
+};
+export type MeDeletionCodeSendErrors = {
+    /**
+     * The request was malformed.
+     */
+    400: Error;
+    /**
+     * Authentication is missing or invalid.
+     */
+    401: Error;
+    /**
+     * The caller is not allowed to perform this action.
+     */
+    403: Error;
+    /**
+     * The request conflicts with current state.
+     */
+    409: Error;
+    /**
+     * Too many requests for this API key or user (or, with failing
+     * credentials, this IP address). Wait `Retry-After` seconds; retries with
+     * the same `Idempotency-Key` are safe.
+     *
+     */
+    429: Error;
+};
+export type MeDeletionCodeSendError = MeDeletionCodeSendErrors[keyof MeDeletionCodeSendErrors];
+export type MeDeletionCodeSendResponses = {
+    /**
+     * The code is on its way.
+     */
+    202: AccountDeletionCode;
+};
+export type MeDeletionCodeSendResponse = MeDeletionCodeSendResponses[keyof MeDeletionCodeSendResponses];
 export type FeatureFlagsListData = {
     body?: never;
     path?: never;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Nohead } from "./client.ts";
 export { APIPromise, Page, PagePromise, type APIResponse, } from "./api-promise.ts";
-export type { ClientOptions, ConditionalRequestOptions, RequestOptions, } from "./core.ts";
+export type { ClientOptions, ConditionalRequestOptions, RequestOptions, RetryEvent, } from "./core.ts";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.ts";
 export type { Uploadable, UploadParams } from "./resources/assets.ts";
 export type * from "./types.ts";

package/dist/resources/assets.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions } from "../core.ts";
 import type { Asset, AssetUpload, AssetUploadCreate, DownloadUrl, ImageUrl } from "../generated/types.gen.ts";
-import type { DeletedListParams, ImageUrlParams } from "../types.ts";
+import type { AssetListParams, ImageUrlParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** What `assets.upload` accepts. A stream needs `byte_size`. */
 export type Uploadable = Blob | ArrayBuffer | Uint8Array | ReadableStream;
@@ -21,6 +21,10 @@ export declare class Assets extends Resource {
      * file). Throws `UploadError` if storage refuses the bytes, and
      * `ValidationError` if the file fails the checks.
      *
+     * With an `idempotencyKey`, running the same upload again resumes it: the
+     * key starts the upload, and an asset that is already `ready` is returned
+     * without sending the bytes again.
+     *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
      */
@@ -32,7 +36,7 @@ export declare class Assets extends Resource {
     createUpload(params: AssetUploadCreate, options?: RequestOptions): APIPromise<AssetUpload>;
     /** Checks an uploaded file and marks the asset `ready`. */
     complete(asset: string, options?: RequestOptions): APIPromise<Asset>;
-    list(params?: DeletedListParams, options?: RequestOptions): PagePromise<Asset>;
+    list(params?: AssetListParams, options?: RequestOptions): PagePromise<Asset>;
     get(asset: string, options?: RequestOptions): APIPromise<Asset>;
     /** Soft-deletes the asset; the file is purged after 30 days. */
     delete(asset: string, options?: RequestOptions): APIPromise<Asset>;

package/dist/resources/assets.js

@@ -8,6 +8,10 @@ export class Assets extends Resource {
      * file). Throws `UploadError` if storage refuses the bytes, and
      * `ValidationError` if the file fails the checks.
      *
+     * With an `idempotencyKey`, running the same upload again resumes it: the
+     * key starts the upload, and an asset that is already `ready` is returned
+     * without sending the bytes again.
+     *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
      */
@@ -25,6 +29,16 @@ export class Assets extends Resource {
                 ((file instanceof Blob && file.type) || "application/octet-stream"),
             byte_size: byteSize,
         }, options);
+        // A replayed start returns the first run's asset, which may be done.
+        if (options?.idempotencyKey) {
+            const current = await this.get(asset.id, {
+                ...options,
+                idempotencyKey: undefined,
+                changeNote: undefined,
+            });
+            if (current.status === "ready")
+                return current;
+        }
         const stream = file instanceof ReadableStream;
         const response = await this.core
             .fetchWithRetries(upload.url, {
@@ -41,7 +55,8 @@ export class Assets extends Resource {
         if (!response.ok) {
             throw new UploadError(`Storage refused the upload of ${asset.filename} (${response.status})`, response.status);
         }
-        return this.complete(asset.id, options);
+        // The key belongs to the start: the API refuses one key on two requests.
+        return this.complete(asset.id, { ...options, idempotencyKey: undefined });
     }
     /**
      * The first step of an upload: a `pending` asset and a presigned URL to

package/dist/types.d.ts

@@ -82,6 +82,14 @@ export interface DeletedListParams extends ListParams {
     /** List deleted items instead (they can be restored for 30 days). */
     deleted?: boolean;
 }
+export interface AssetListParams extends DeletedListParams {
+    /**
+     * Only assets of these MIME types or `type/*` wildcards, e.g.
+     * `["image/*", "application/pdf"]`, such as an asset field's
+     * `accepted_types`.
+     */
+    content_type?: string | string[];
+}
 export interface SchemaParams {
     /** A past schema version; the current one otherwise. */
     version?: number;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",