@sixtyninecommerce/admin 0.6.0 → 0.7.0

package/dist/uploads/index.d.ts

@@ -0,0 +1,146 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * What an upload is for. It decides which permission stages it and who may
+ * consume it.
+ *
+ * `asset` is the only purpose today. `bulk` and `document` arrive with the
+ * calls that consume them, each with its own storage decision — everything
+ * staged currently lands in the public asset bucket, which is right for a media
+ * asset and not for a customer export or an order attachment.
+ */
+export type UploadPurpose = 'asset';
+export type UploadStatus = 'staged' | 'consumed' | 'expired';
+export interface StagedUpload {
+    id: string;
+    purpose: UploadPurpose;
+    status: UploadStatus;
+    mimeType: string;
+    /**
+     * The EXACT size the signature was computed for, as a string.
+     *
+     * A string because it is a 64-bit column and a JSON number is a double; use
+     * `Number(...)` if you need arithmetic, which is exact below 2^53.
+     */
+    sizeBytes: string;
+    /** The label you gave the file. It is never part of the object's location. */
+    filename: string | null;
+    /** When the RESERVATION lapses. After this nothing will accept the upload. */
+    expiresAt: string;
+    consumedAt: string | null;
+    createdAt: string;
+}
+export interface StagedUploadTicket extends StagedUpload {
+    /** PUT the bytes here. Single use. */
+    url: string;
+    method: 'PUT';
+    /**
+     * Send ALL of these, spelled exactly like this. They are part of the
+     * signature, so storage refuses a PUT that omits or changes one.
+     */
+    headers: Record<string, string>;
+    /**
+     * When the URL stops working — at most {@link StagedUpload.expiresAt}, and
+     * less than it when you re-staged an upload that was already running down.
+     */
+    urlExpiresAt: string;
+}
+export interface StageUploadInput {
+    purpose: UploadPurpose;
+    /** Checked against the platform allow-list and bound into the signature. */
+    mimeType: string;
+    /**
+     * The EXACT number of bytes you will send — not a maximum.
+     *
+     * A presigned PUT can only pin a precise `Content-Length`; there is no way to
+     * sign an upper bound. Storage refuses any other length, so this must be the
+     * real size of the body (`blob.size`, `buffer.length`, `stat.size`).
+     */
+    size: number;
+    /**
+     * Your own handle for this upload, making the call repeatable.
+     *
+     * Required. Staging is the call that hands out a URL, and a dropped response
+     * on it is the ordinary failure: without a token every retry would reserve
+     * another place and leave an object nobody ever claims. Staging twice with
+     * the same token returns the SAME upload; staging DIFFERENT terms under it is
+     * refused with `UPLOAD_TOKEN_CONFLICT`.
+     */
+    clientToken: string;
+    /** A label for humans. It never reaches the object's location. */
+    filename?: string;
+}
+/**
+ * Bytes this SDK knows how to PUT. A `Blob` in any modern runtime, or a
+ * `Uint8Array`/`ArrayBuffer` from Node.
+ */
+export type UploadBody = Blob | ArrayBuffer | ArrayBufferView;
+export interface ClaimAsAssetInput {
+    /** Place the asset in this CMS asset folder. */
+    folderId?: string;
+    altText?: string;
+}
+/**
+ * Signed direct-to-storage uploads (spec §6.11).
+ *
+ * **The shape of it.** You say what you are uploading; the platform decides
+ * WHERE it goes and signs exactly that. You never see or choose a path. The
+ * three steps are `stage` (reserve and get a URL), `put` (send the bytes
+ * straight to storage — they do not pass through the platform), and a consuming
+ * call that takes the upload's id.
+ *
+ * ```ts
+ * const bytes = await readFile('hero.png');
+ * const ticket = await admin.uploads.stage({
+ *   purpose: 'asset',
+ *   mimeType: 'image/png',
+ *   size: bytes.length,
+ *   clientToken: crypto.randomUUID(),
+ *   filename: 'hero.png',
+ * });
+ * await admin.uploads.put(ticket, bytes);
+ * const asset = await admin.uploads.claimAsAsset(ticket.id, { altText: 'Our hero' });
+ * ```
+ *
+ * **The size is exact.** `size` is the byte count storage will accept and no
+ * other — not a ceiling. Sending a different number of bytes fails at storage
+ * with a signature error, so compute it from the body you are about to send.
+ *
+ * **One use, and a window scaled to the size.** A URL writes one object, once.
+ * The reservation lasts at least fifteen minutes, and longer for a large file —
+ * enough to send it at about 1 Mbit/s — because a window too short to upload in
+ * would expire between the PUT and the claim. `expiresAt` is the reservation;
+ * `urlExpiresAt` is the signature, and never outlives it. An upload nobody
+ * consumes expires and its bytes are deleted.
+ *
+ * **It is yours alone.** An upload is visible and usable only to the principal
+ * that staged it, on the store it was staged for. Anything else answers
+ * `UPLOAD_NOT_FOUND` — the same answer as an id that never existed.
+ *
+ * **Browsers need CORS.** `put` sends a cross-origin PUT to the object store,
+ * which requires CORS rules on the bucket that this platform does not
+ * configure. Server-side callers are unaffected.
+ */
+export interface UploadsModule {
+    /** Reserve a place and get a signed URL to PUT one file to. */
+    stage(input: StageUploadInput, options?: Call): Promise<StagedUploadTicket>;
+    /**
+     * Send the bytes to storage using the ticket's URL and headers.
+     *
+     * It does NOT go through the platform and carries none of your credentials —
+     * the URL is the authorisation. Resolves on a 2xx and throws the store's
+     * status otherwise.
+     */
+    put(ticket: StagedUploadTicket, body: UploadBody): Promise<void>;
+    /** One upload's state. Unknown, or another principal's, is `UPLOAD_NOT_FOUND`. */
+    get(id: string, options?: Call): Promise<StagedUpload>;
+    /**
+     * Turn a staged upload into a CMS asset.
+     *
+     * This is the consuming call: it verifies the object is there and is what was
+     * signed, spends the upload, and ingests the bytes. An upload can be consumed
+     * once — a second call is `UPLOAD_ALREADY_CONSUMED`.
+     */
+    claimAsAsset(id: string, input?: ClaimAsAssetInput, options?: Call): Promise<unknown>;
+}
+export declare function createUploadsModule(transport: Transport, fetchImpl: typeof globalThis.fetch): UploadsModule;

package/dist/uploads/index.js

@@ -0,0 +1,72 @@
+import { PLATFORM_PASSTHROUGH_KEYS, ValidationError, } from '@sixtyninecommerce/core';
+/**
+ * `headers` carries the exact header NAMES a signature was computed over.
+ *
+ * Case-converting them would rewrite `content-type` to `contentType`, and the
+ * PUT would then go out without the header storage is checking for — a
+ * signature failure that looks like a credential problem and is not.
+ */
+const PRESERVE = new Set([...PLATFORM_PASSTHROUGH_KEYS, 'headers']);
+export function createUploadsModule(transport, fetchImpl) {
+    return {
+        async stage(input, options) {
+            if (!Number.isSafeInteger(input.size) || input.size < 1) {
+                // Refused here rather than sent: a fractional or negative size would be
+                // rejected by the service as a validation failure whose message is
+                // about a field the caller did not type, and `size: NaN` from a missing
+                // `blob.size` is the way this goes wrong in practice.
+                throw new ValidationError({
+                    code: 'UPLOAD_SIZE_INVALID',
+                    message: `size must be the exact whole number of bytes you will upload; received ${String(input.size)}.`,
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            return await transport.rest('plugins', {
+                method: 'POST',
+                path: '/uploads/stage',
+                body: {
+                    purpose: input.purpose,
+                    mime_type: input.mimeType,
+                    size_bytes: input.size,
+                    client_token: input.clientToken,
+                    ...(input.filename === undefined ? {} : { filename: input.filename }),
+                },
+            }, { ...options, preserveKeys: PRESERVE });
+        },
+        async put(ticket, body) {
+            const response = await fetchImpl(ticket.url, {
+                method: ticket.method,
+                // Exactly what was signed, and nothing else. An extra header is
+                // harmless, but a MISSING or altered one is a signature failure.
+                headers: { ...ticket.headers },
+                body: body,
+            });
+            if (!response.ok) {
+                const detail = await response.text().catch(() => '');
+                throw new ValidationError({
+                    code: 'UPLOAD_PUT_REFUSED',
+                    message: `The object store refused the upload (HTTP ${String(response.status)}). The commonest causes are a body whose length is not the \`size\` this upload was staged for, ` +
+                        `a changed \`content-type\`, and a URL that has expired.${detail ? ` Store said: ${detail.slice(0, 300)}` : ''}`,
+                    status: response.status,
+                    service: 'plugins',
+                });
+            }
+        },
+        async get(id, options) {
+            return await transport.rest('plugins', { method: 'GET', path: `/uploads/${encodeURIComponent(id)}` }, { ...options, preserveKeys: PRESERVE });
+        },
+        async claimAsAsset(id, input, options) {
+            const body = await transport.rest('cms', {
+                method: 'POST',
+                path: '/assets/from-staged',
+                body: {
+                    staged_upload_id: id,
+                    ...(input?.folderId === undefined ? {} : { folder_id: input.folderId }),
+                    ...(input?.altText === undefined ? {} : { alt_text: input.altText }),
+                },
+            }, options);
+            return body.data;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Back-office SDK for sixtynine-commerce: every capability of the platform as a method",
   "homepage": "https://github.com/SIXTYNINE-digital/sixtynine-commerce-engine/tree/main/packages/admin-client#readme",
   "repository": {
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sixtyninecommerce/core": "^0.3.0"
+    "@sixtyninecommerce/core": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "22.19.7",
@@ -41,7 +41,7 @@
     "vitest": "4.1.6"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",