@segmentstream-cloud/app 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -30,3 +30,4 @@ export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";
 export type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
 export type { AppUser } from "./tokens.js";
+export { createBlobStorageClient, type BlobUploadTicket, type FileRevision, type FileTransfer, type FileUploadTarget, type UploadSession, type FileUploadOptions, } from "./storage.js";

package/dist/index.js

@@ -19,3 +19,4 @@ export function createSegmentStreamApp(config) {
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { createBlobStorageClient, } from "./storage.js";

package/dist/ontology-wire.js

@@ -233,11 +233,13 @@ export function actionInputToWire(input, entity, action, catalog) {
         const property = definition?.properties.find((candidate) => candidate.name === wireField);
         return [
             wireField,
-            (action === "link" || action === "unlink") &&
-                field === "relationship" &&
-                typeof child === "string"
-                ? toSnakeCase(child)
-                : selectToWire(child, property),
+            property?.type === "blob" && isRecord(child)
+                ? Object.fromEntries(Object.entries(child).map(([key, value]) => [toSnakeCase(key), value]))
+                : (action === "link" || action === "unlink") &&
+                    field === "relationship" &&
+                    typeof child === "string"
+                    ? toSnakeCase(child)
+                    : selectToWire(child, property),
         ];
     }));
 }

package/dist/ontology.d.ts

@@ -121,6 +121,8 @@ export interface RequestOptions {
 export interface ActionOptions extends RequestOptions {
     /** Validate the input and report issues in `validation` without a write. */
     readonly validateOnly?: boolean;
+    readonly idempotencyKey?: string;
+    readonly createIntent?: string;
 }
 export interface HistoryOptions extends RequestOptions {
     readonly after?: string;

package/dist/ontology.js

@@ -89,9 +89,21 @@ function entityClient(entity, transport, getCatalog) {
         const catalog = await getCatalog();
         const wireResponse = await send(transport, "POST", `${base}/actions/${encodeURIComponent(action)}`, {
             input: actionInputToWire(input, entity, action, catalog),
-            ...(options.validateOnly === undefined
+            ...([options.validateOnly, options.idempotencyKey, options.createIntent].every((value) => value === undefined)
                 ? {}
-                : { options: { validate_only: options.validateOnly } }),
+                : {
+                    options: {
+                        ...(options.validateOnly === undefined
+                            ? {}
+                            : { validate_only: options.validateOnly }),
+                        ...(options.idempotencyKey === undefined
+                            ? {}
+                            : { idempotency_key: options.idempotencyKey }),
+                        ...(options.createIntent === undefined
+                            ? {}
+                            : { create_intent: options.createIntent }),
+                    },
+                }),
         }, options.signal);
         const response = { ...wireResponse, edits: editsFromWire(wireResponse.edits, catalog) };
         if (action === "create" || action === "update") {

package/dist/storage.d.ts

@@ -0,0 +1,54 @@
+import type { OntologyTransport } from "./ontology.js";
+export interface BlobUploadTicket {
+    readonly uploadId: string;
+}
+export interface FileRevision {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly createdAt: string;
+}
+export interface FileTransfer {
+    readonly url: string;
+    readonly method: "GET" | "PUT";
+    readonly headers: Readonly<Record<string, string>>;
+    readonly expiresAt: string;
+}
+export interface FileUploadTarget {
+    readonly entity: string;
+    readonly property: string;
+    readonly action: string;
+    readonly recordId?: string;
+    readonly createIntent?: string;
+}
+export interface UploadSession {
+    readonly id: string;
+    readonly state: string;
+    readonly expiresAt: string;
+    readonly ticket?: BlobUploadTicket;
+}
+export interface FileUploadOptions {
+    readonly signal?: AbortSignal;
+    /** Reuse this UUID when retrying an upload and its entity action. */
+    readonly idempotencyKey?: string;
+    /** Reports transfer start and completion; supply a transfer adapter for granular progress. */
+    readonly onProgress?: (transferred: number, total: number) => void;
+}
+/** Portable client: ontology requests use the member transport; bytes use only a scoped grant. */
+export declare function createBlobStorageClient(transport: OntologyTransport, transfer?: typeof fetch): {
+    status: (id: string, signal?: AbortSignal) => Promise<UploadSession>;
+    cancel: (id: string) => Promise<UploadSession>;
+    uploadForAction(target: FileUploadTarget, file: File, options?: FileUploadOptions): Promise<{
+        ticket: BlobUploadTicket;
+        options: {
+            createIntent?: string | undefined;
+            idempotencyKey: string;
+        };
+    }>;
+    download(entity: string, recordId: string, property: string, options?: {
+        readonly revisionId?: string;
+        readonly inline?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<FileTransfer>;
+};

package/dist/storage.js

@@ -0,0 +1,116 @@
+import { apiErrorFrom, readJson } from "./errors.js";
+import { toSnakeCase } from "./ontology-names.js";
+/** Portable client: ontology requests use the member transport; bytes use only a scoped grant. */
+export function createBlobStorageClient(transport, transfer = globalThis.fetch) {
+    const send = async (path, method, body, signal) => {
+        const response = await transport.fetch(path, {
+            method,
+            ...(body === undefined
+                ? {}
+                : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+            ...(signal ? { signal } : {}),
+        });
+        const data = await readJson(response);
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, data, "The ontology service rejected the file request.");
+        }
+        return data;
+    };
+    const sessionPath = (id) => `/uploads/${encodeURIComponent(id)}`;
+    const readSession = async (path, method, body, signal) => {
+        const { expires_at, ticket, ...session } = await send(path, method, body, signal);
+        return {
+            ...session,
+            expiresAt: expires_at,
+            ...(ticket ? { ticket: { uploadId: ticket.upload_id } } : {}),
+        };
+    };
+    const readTransfer = async (path, body, signal) => {
+        const { expires_at, ...grant } = await send(path, "POST", body, signal);
+        return { ...grant, expiresAt: expires_at };
+    };
+    const cancel = (id) => readSession(`${sessionPath(id)}/cancel`, "POST");
+    return {
+        status: (id, signal) => readSession(sessionPath(id), "GET", undefined, signal),
+        cancel,
+        async uploadForAction(target, file, options = {}) {
+            const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+            const createIntent = target.recordId ? undefined : (target.createIntent ?? idempotencyKey);
+            const session = await readSession("/uploads", "POST", {
+                entity: toSnakeCase(target.entity),
+                property: toSnakeCase(target.property),
+                action: toSnakeCase(target.action),
+                ...(target.recordId ? { record_id: target.recordId } : {}),
+                ...(createIntent ? { create_intent: createIntent } : {}),
+                idempotency_key: idempotencyKey,
+                filename: file.name,
+                content_type: file.type,
+                size: file.size,
+            }, options.signal);
+            if (session.ticket) {
+                return {
+                    ticket: session.ticket,
+                    options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                };
+            }
+            let completionStarted = false;
+            let transferRejected = false;
+            try {
+                if (session.state !== "completing") {
+                    const grant = await readTransfer(`${sessionPath(session.id)}/parts`, undefined, options.signal);
+                    options.onProgress?.(0, file.size);
+                    const response = await transfer(grant.url, {
+                        method: grant.method,
+                        headers: grant.headers,
+                        body: file,
+                        signal: options.signal,
+                        credentials: "omit",
+                        referrerPolicy: "no-referrer",
+                    });
+                    if (!response.ok) {
+                        transferRejected = true;
+                        throw new Error(`File transfer failed (${response.status}).`);
+                    }
+                    options.onProgress?.(file.size, file.size);
+                }
+                completionStarted = true;
+                const completed = await readSession(`${sessionPath(session.id)}/complete`, "POST", undefined, options.signal);
+                if (!completed.ticket) {
+                    throw new Error("The file upload is not ready.");
+                }
+                return {
+                    ticket: completed.ticket,
+                    options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                };
+            }
+            catch (error) {
+                if (options.signal?.aborted || transferRejected) {
+                    // Deliberate cancellation uses a fresh request even when the signal was aborted.
+                    await cancel(session.id).catch((cause) => {
+                        console.warn("ontology.upload.cancel_failed", { uploadId: session.id, cause });
+                    });
+                }
+                else if (completionStarted) {
+                    // A lost completion response may already have produced a valid ticket.
+                    const recovered = await readSession(sessionPath(session.id), "GET").catch(() => undefined);
+                    if (recovered?.ticket) {
+                        return {
+                            ticket: recovered.ticket,
+                            options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                        };
+                    }
+                }
+                // Ambiguous network failures retain the session for an explicit retry or scheduled cleanup.
+                throw error;
+            }
+        },
+        download(entity, recordId, property, options = {}) {
+            const { signal } = options;
+            const input = {
+                ...(options.revisionId ? { revision_id: options.revisionId } : {}),
+                ...(options.inline === undefined ? {} : { inline: options.inline }),
+            };
+            return readTransfer(`/${encodeURIComponent(toSnakeCase(entity))}/${encodeURIComponent(recordId)}/blobs/${encodeURIComponent(toSnakeCase(property))}/download`, input, signal);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -27,7 +27,11 @@
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js"
     },
-    "./ui/styles.css": "./dist/ui/styles.css"
+    "./ui/styles.css": "./dist/ui/styles.css",
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    }
   },
   "files": [
     "dist",