@nohead/sdk 0.7.0 → 0.9.0

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

@@ -1,5 +1,5 @@
 export type ClientOptions = {
-    baseUrl: 'https://api.nohead.io' | 'http://localhost:3000' | (string & {});
+    baseUrl: 'https://api.nohead.io' | (string & {});
 };
 export type Webhooks = WebhookEventWebhookRequest;
 export type RequestId = string;
@@ -1129,7 +1129,7 @@ export type Principal = {
         email: string;
         name: string | null;
         /**
-         * Nohead staff (internal tooling access).
+         * Whether the user is Nohead staff.
          */
         staff: boolean;
     };
@@ -1539,6 +1539,25 @@ export type AssetProperties = {
      * The URL of a small rendition (fits in 640×640, WebP), for ready images and SVGs (rasterized; SVGs have no `image_url`), deleted ones included until they are purged; null otherwise.
      */
     preview_url: string | null;
+    /**
+     * The URL of the file as uploaded, for ready assets of any type,
+     * deleted ones included until they are purged; null otherwise. It
+     * downloads the file under its `filename` (a rename applies within a
+     * minute or so), is open and never expires, and is cached on a CDN.
+     *
+     */
+    file_url: string | null;
+    /**
+     * The URL that plays a ready video or audio file inline, for
+     * `<video>` and `<audio>` (with range requests, so players can seek),
+     * deleted ones included until they are purged: MP4, QuickTime, M4A,
+     * 3GP, WebM, Matroska, MP3, AAC, FLAC, WAV and Ogg (whose content is
+     * checked when the upload completes). Null for other types, which
+     * `file_url` downloads.
+     * Open, never expiring and cached on a CDN, like `file_url`.
+     *
+     */
+    media_url: string | null;
     uploaded_at: NullableTimestamp;
     created_at: Timestamp;
     updated_at: Timestamp;
@@ -1569,17 +1588,11 @@ export type AssetUsage = {
         fields: Array<string>;
     }>;
 };
-export type DownloadUrl = {
-    object: 'download_url';
-    asset_id: string;
-    url: string;
-    expires_at: Timestamp;
-};
 export type AssetUploadCreate = {
     filename: string;
     content_type: string;
     /**
-     * Exact size of the file in bytes (at most 100 MB by default).
+     * Exact size of the file in bytes, at most the plan's largest upload (10 MB on Free, 100 MB on paid plans).
      */
     byte_size: number;
 };
@@ -1609,7 +1622,7 @@ export type AssetUploadTarget = {
     expires_at: Timestamp;
 };
 /**
- * What a project API key may do. `records:write` also publishes, unpublishes and schedules records (the `records:publish` permission). `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
+ * What a project API key may do. `records:write` also publishes, unpublishes and schedules records. `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
  */
 export type ApiKeyScope = 'records:read' | 'records:write' | 'schema:read' | 'schema:write' | 'assets:read' | 'assets:write' | 'search:read' | 'webhooks:read' | 'webhooks:write' | 'audit:read';
 /**
@@ -5741,55 +5754,6 @@ export type AssetsUpdateResponses = {
     200: Asset;
 };
 export type AssetsUpdateResponse = AssetsUpdateResponses[keyof AssetsUpdateResponses];
-export type AssetsDownloadUrlData = {
-    body?: never;
-    path: {
-        asset_id: string;
-    };
-    query?: never;
-    url: '/v1/assets/{asset_id}/download-url';
-};
-export type AssetsDownloadUrlErrors = {
-    /**
-     * The request was malformed: unparseable JSON, an invalid query parameter, or a body key the operation doesn't take (detail code `unknown_parameter`, naming the key).
-     */
-    400: Error;
-    /**
-     * Authentication is missing or invalid.
-     */
-    401: Error;
-    /**
-     * The caller is not allowed to perform this action.
-     */
-    403: Error;
-    /**
-     * The resource does not exist or is not visible to the caller.
-     */
-    404: 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). A published-only key is counted per
-     * client IP. Wait `Retry-After` seconds; retries with the same `Idempotency-Key`
-     * are safe. On the Free plan, an organization's API keys are also
-     * refused once its API requests reach the month's limit, with a
-     * `plan_limit` detail (`field` `api_requests`, `usage` and `limit`),
-     * until the next month (UTC) or an upgrade.
-     *
-     */
-    429: Error;
-};
-export type AssetsDownloadUrlError = AssetsDownloadUrlErrors[keyof AssetsDownloadUrlErrors];
-export type AssetsDownloadUrlResponses = {
-    /**
-     * The download URL.
-     */
-    200: DownloadUrl;
-};
-export type AssetsDownloadUrlResponse = AssetsDownloadUrlResponses[keyof AssetsDownloadUrlResponses];
 export type AssetsUsageData = {
     body?: never;
     path: {

package/dist/images.js

@@ -16,8 +16,13 @@ export function imageUrl(image, options = {}) {
     const at = base.indexOf("/plain/");
     if (at < 0)
         throw new TypeError(`Not a Nohead image URL: ${base}`);
-    const { width, height, fit = "contain", format, quality, dpr, gravity, } = options;
-    for (const option of [gravity, ...(options.options ?? [])])
+    // Empty options count as unset.
+    const { width, height, format, quality, dpr, gravity } = options;
+    const fit = options.fit || "contain";
+    if (!Object.hasOwn(FITS, fit))
+        throw new TypeError(`fit must be one of ${Object.keys(FITS).join(", ")}`);
+    const others = (options.options ?? []).filter(Boolean);
+    for (const option of [gravity, ...others])
         if (option && /[/@?#]/.test(option))
             throw new TypeError(`Not an imgproxy option: ${option}`);
     const segments = [];
@@ -29,7 +34,7 @@ export function imageUrl(image, options = {}) {
         segments.push(`dpr:${dpr}`);
     if (quality)
         segments.push(`q:${quality}`);
-    segments.push(...(options.options ?? []));
+    segments.push(...others);
     // The source comes last; a format replaces any the URL already names.
     let source = base.slice(at);
     if (format)

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, ConditionalWriteOptions, RequestOptions, RetryEvent, WriteOptions, } from "./core.ts";
+export { DEFAULT_BASE_URL, type ClientOptions, type ConditionalRequestOptions, type ConditionalWriteOptions, type CopyOptions, type RequestOptions, type RetryEvent, type WriteOptions, } 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/index.js

@@ -1,5 +1,6 @@
 export { Nohead } from "./client.js";
 export { APIPromise, Page, PagePromise, } from "./api-promise.js";
+export { DEFAULT_BASE_URL, } from "./core.js";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.js";
 export { unwrapWebhook, } from "./webhooks.js";
 export { VERSION } from "./version.js";

package/dist/resources/assets.d.ts

@@ -1,6 +1,6 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions } from "../core.ts";
-import type { Asset, AssetUpdate, AssetUploadCreate, AssetWithUpload, AssetUsage, DownloadUrl } from "../generated/types.gen.ts";
+import type { Asset, AssetUpdate, AssetUploadCreate, AssetWithUpload, AssetUsage } from "../generated/types.gen.ts";
 import type { AssetListParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** What `assets.upload` accepts. A stream needs `byte_size`. */
@@ -8,11 +8,15 @@ export type Uploadable = Blob | ArrayBuffer | Uint8Array | ReadableStream;
 export interface UploadParams {
     /** Defaults to a `File`'s name, else `upload`. */
     filename?: string;
-    /** Defaults to the `Blob`'s type, else `application/octet-stream`. */
+    /**
+     * Defaults to the `Blob`'s type, else the filename's extension's for
+     * common files, else `application/octet-stream`.
+     */
     content_type?: string;
     /** Required for a `ReadableStream`; known for everything else. */
     byte_size?: number;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export declare class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -69,6 +73,4 @@ export declare class Assets extends Resource {
      * updated with the fields that use it (`uses`). Needs `records:read` too.
      */
     usage(asset: string, options?: RequestOptions): APIPromise<AssetUsage>;
-    /** A link to download the original file (`url`), valid for 2 minutes. */
-    downloadUrl(asset: string, options?: RequestOptions): APIPromise<DownloadUrl>;
 }

package/dist/resources/assets.js

@@ -1,6 +1,5 @@
 import { AbortError, UploadError } from "../errors.js";
 import { listQuery, Resource } from "./resource.js";
-/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 /** Common files' types by extension, as the other SDKs guess them. */
 const CONTENT_TYPES = {
     avif: "image/avif",
@@ -26,6 +25,7 @@ function contentTypeOf(filename) {
         ? CONTENT_TYPES[filename.slice(dot + 1).toLowerCase()]
         : undefined;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -45,23 +45,28 @@ export class Assets extends Resource {
      * extension's for common files.
      */
     async upload(file, params = {}, options) {
+        // Never a path: the Python and Ruby SDKs take one, so it would be easy
+        // to send its text instead.
+        if (typeof file === "string") {
+            throw new TypeError("upload takes a Blob, File, ArrayBuffer, Uint8Array or ReadableStream; to upload a file from disk, pass await fs.openAsBlob(path)");
+        }
         const byteSize = params.byte_size ?? sizeOf(file);
         if (byteSize === undefined) {
             throw new UploadError("Uploading a stream needs `byte_size`");
         }
-        const filename = params.filename ??
-            (typeof File !== "undefined" && file instanceof File
-                ? file.name
-                : "upload");
+        // Empty ones count as unset.
+        const filename = params.filename ||
+            (typeof File !== "undefined" && file instanceof File && file.name) ||
+            "upload";
         const { upload, ...asset } = await this.createUpload({
             filename,
             // The Blob's own type, or one the filename's extension implies (a
             // Blob from Node's openAsBlob has none), as the Python and Ruby
             // SDKs do.
-            content_type: params.content_type ??
-                ((file instanceof Blob && file.type) ||
-                    contentTypeOf(filename) ||
-                    "application/octet-stream"),
+            content_type: params.content_type ||
+                (file instanceof Blob && file.type) ||
+                contentTypeOf(filename) ||
+                "application/octet-stream",
             byte_size: byteSize,
         }, options);
         // A replayed start returns the first run's asset, which may be done.
@@ -74,24 +79,28 @@ export class Assets extends Resource {
                 return current;
             // The key replays the first run's upload URL, which expires sooner.
             if (Date.parse(upload.expires_at) <= Date.now()) {
-                throw new UploadError(`The upload of ${asset.filename} expired: start it again with a new idempotencyKey`);
+                throw new UploadError(`The upload of ${filename} expired: start it again with a new idempotencyKey`);
             }
         }
         const stream = file instanceof ReadableStream;
         const response = await this.core
             .fetchWithRetries(upload.url, {
             method: upload.method,
-            headers: upload.headers,
+            // The URL is signed for this size; fetch would send a stream
+            // in chunks, without one.
+            headers: stream
+                ? { ...upload.headers, "Content-Length": String(byteSize) }
+                : upload.headers,
             body: file,
             ...(stream ? { duplex: "half" } : {}),
-        }, { ...options, retry: !stream })
+        }, { ...options, retry: !stream, byteSize })
             .catch((error) => {
             if (error instanceof AbortError)
                 throw error;
-            throw new UploadError(`Could not upload ${asset.filename}: ${error.message}`, undefined, { cause: error });
+            throw new UploadError(`Could not upload ${filename}: ${error.message}`, undefined, { cause: error });
         });
         if (!response.ok) {
-            throw new UploadError(`Storage refused the upload of ${asset.filename} (${response.status})`, response.status);
+            throw new UploadError(`Storage refused the upload of ${filename} (${response.status})`, response.status);
         }
         // The key belongs to the start: the API refuses one key on two requests.
         return this.complete(asset.id, { ...options, idempotencyKey: undefined });
@@ -159,10 +168,6 @@ export class Assets extends Resource {
     usage(asset, options) {
         return this.core.request("assets_usage", { path: { asset_id: asset } }, options);
     }
-    /** A link to download the original file (`url`), valid for 2 minutes. */
-    downloadUrl(asset, options) {
-        return this.core.request("assets_download_url", { path: { asset_id: asset } }, options);
-    }
 }
 function sizeOf(file) {
     if (file instanceof Blob)

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.7.0";
+export const VERSION = "0.9.0";

package/dist/webhooks.d.ts

@@ -49,8 +49,9 @@ export interface UnwrapOptions {
     /**
      * The webhook's signing secret (`whsec_…`). While a rotation overlaps,
      * requests carry a signature for each secret, so either one verifies.
+     * An unset one (as from a missing environment variable) throws.
      */
-    secret: string;
+    secret: string | undefined;
     /** Seconds a timestamp may be off from now. Default 300. */
     tolerance?: number;
 }

package/dist/webhooks.js

@@ -24,7 +24,11 @@ export async function unwrapWebhook(body, headers, { secret, tolerance = 300 })
         throw new WebhookVerificationError("The webhook timestamp is too far from the current time");
     }
     const text = typeof body === "string" ? body : new TextDecoder().decode(body);
-    const key = await crypto.subtle.importKey("raw", decodeBase64(secret.replace(/^whsec_/, ""), "secret"), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const keyBytes = decodeBase64((secret ?? "").replace(/^whsec_/, ""), "secret");
+    if (keyBytes.length === 0) {
+        throw new WebhookVerificationError("The webhook secret is empty");
+    }
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
     const signed = new TextEncoder().encode(`${id}.${timestamp}.${text}`);
     for (const entry of signatures.split(" ")) {
         const [version, signature] = entry.split(",", 2);
@@ -63,8 +67,5 @@ function decodeBase64(value, what) {
     catch {
         throw new WebhookVerificationError(`The webhook ${what} is not base64`);
     }
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -61,6 +61,7 @@
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
     "prettier": "^3.9.9",
+    "standardwebhooks": "^1.1.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.0",
     "vitest": "^5.0.3"