@segmentstream-cloud/app 0.6.0 → 0.8.0

package/README.md

@@ -1,10 +1,11 @@
 # @segmentstream-cloud/app
 
-The ontology client uses snake_case entity fields and action names. Its TypeScript
-options remain camelCase; it maps `orderBy`, `isNull`, `startsWith`, and
-`validateOnly` to the generated REST contract and returns pagination/history
-metadata as camelCase. Queries using multiword filter operators lazily read and
-cache the ontology catalog so JSON property contents remain unchanged.
+The ontology client uses camelCase entities, records and actions, including
+`createdAt`, `assignedOwnerId`, and `actions.changeStatus(...)`. It translates
+queries and declared action inputs to snake_case REST and decodes records back to
+camelCase. The catalog is read lazily and cached by ontology hash so nested
+relationships and select identifiers convert while JSON property contents,
+provider payloads and opaque action results remain unchanged.
 
 Sign-in, users, permissions, the ontology client and warehouse data access for
 SegmentStream workspace apps built with Next.js (App Router, version 16 or later) and
@@ -117,7 +118,7 @@ authUserId?, organizationId, workspaceId }`. `id` is the person's ontology `user
   or use another email.
 - `getUser()` returns the same, or `null` when signed out; it throws
   `SegmentStreamApiError` with `code: "not_invited"` for people without an invitation.
-- `can("lead:change_status")` is `true` when the user's permissions cover the
+- `can("lead:changeStatus")` is `true` when the user's permissions cover the
   permission. Roles may hold wildcards: `lead:*`, `*:read`, `*:*`. `isAllowed` and
   `grants` apply the same rule to any list of permissions.
 - `signOut()` ends the session, clears its cookies and redirects to `/sign-in` (or
@@ -132,22 +133,22 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 (no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
 `:root` set colours, radius and font.
 
-| Export                                  | Does                                                                            |
-| --------------------------------------- | ------------------------------------------------------------------------------- |
-| `<SignIn />`                            | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
-| `useSignIn()`                           | The same sign-in without markup, for the app's own form                         |
-| `<SignedIn>`, `<SignedOut>`             | Render children by session state                                                |
-| `<Can permission="lead:change_status">` | Renders children when the user holds the permission; `fallback` otherwise       |
-| `<UserMenu />`                          | Name, email, roles and sign-out                                                 |
-| `useUser()`                             | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
-| `usePermissions()`                      | `{ isLoading, roles, permissions, can(permission) }`                            |
-| `useSession()`, `signOut()`             | The Neon Auth session in the browser; sign-out from the browser                 |
+| Export                                 | Does                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `<SignIn />`                           | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
+| `useSignIn()`                          | The same sign-in without markup, for the app's own form                         |
+| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                |
+| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise       |
+| `<UserMenu />`                         | Name, email, roles and sign-out                                                 |
+| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
+| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
+| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                 |
 
 `<Can>` only hides controls: the ontology service checks every read and action. A
 Server Component may wrap server-rendered children in `<Can>`:
 
 ```tsx
-<Can permission="lead:change_status" fallback={lead.status}>
+<Can permission="lead:changeStatus" fallback={lead.status}>
   <ChangeStatusForm lead={lead.id} />
 </Can>
 ```
@@ -260,7 +261,7 @@ Records, action inputs and action results are typed from the ontology:
 ```ts
 const { items, nextCursor } = await segmentstream.ontology.lead.find({
   where: { status: { in: ["new", "contacted"] } },
-  orderBy: [{ field: "created_at", direction: "desc" }],
+  orderBy: [{ field: "createdAt", direction: "desc" }],
   include: { owner: true },
   limit: 20,
 });
@@ -269,11 +270,10 @@ const history = await segmentstream.ontology.lead.history(id, { limit: 50 });
 const page = await segmentstream.ontology.lead.query({ where: { email: { startsWith: "ada" } } });
 
 const input = { lead: id, status: "contacted" } as const;
-const check = await segmentstream.ontology.lead.actions.change_status(input, {
+const check = await segmentstream.ontology.lead.actions.changeStatus(input, {
   validateOnly: true,
 });
-const { result, validation, edits } =
-  await segmentstream.ontology.lead.actions.change_status(input);
+const { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
 ```
 
 - `find` sends the query as URL parameters, `query` as a JSON body; both return

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/me.d.ts

@@ -1,4 +1,3 @@
-/** The ontology service's account of the caller: `GET /api/ontology/me`. */
 export declare const ME_PATH = "/api/ontology/me";
 /**
  * The signed-in person as the ontology knows them: their `user` record, the roles they hold and the

package/dist/me.js

@@ -1,4 +1,5 @@
 /** The ontology service's account of the caller: `GET /api/ontology/me`. */
+import { toCamelCase } from "./ontology-names.js";
 export const ME_PATH = "/api/ontology/me";
 /**
  * Reads `{ user: { id, name, email, kind, active }, roles, permissions }` tolerantly: unknown
@@ -22,8 +23,8 @@ export function parseMe(payload) {
         email: typeof email === "string" ? email : null,
         kind: typeof kind === "string" ? kind : "member",
         active: typeof active === "boolean" ? active : true,
-        roles: strings(roles),
-        permissions: strings(permissions),
+        roles: strings(roles).map(toCamelCase),
+        permissions: strings(permissions).map(toCamelCase),
     };
 }
 function strings(value) {

package/dist/ontology-names.d.ts

@@ -0,0 +1,3 @@
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export declare function toSnakeCase(name: string): string;
+export declare function toCamelCase(name: string): string;

package/dist/ontology-names.js

@@ -0,0 +1,26 @@
+/** Ontology identifiers in TypeScript and their canonical transport spelling. */
+function isUppercase(letter) {
+    return letter !== undefined && letter >= "A" && letter <= "Z";
+}
+function isLowercase(letter) {
+    return letter !== undefined && letter >= "a" && letter <= "z";
+}
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export function toSnakeCase(name) {
+    const characters = [];
+    for (let index = 0; index < name.length; index++) {
+        const current = name[index];
+        const previous = name[index - 1];
+        const next = name[index + 1];
+        const followsWord = isLowercase(previous) || (previous !== undefined && previous >= "0" && previous <= "9");
+        const endsAcronym = isUppercase(previous) && isLowercase(next);
+        if (isUppercase(current) && (followsWord || endsAcronym)) {
+            characters.push("_");
+        }
+        characters.push(current);
+    }
+    return characters.join("").toLowerCase();
+}
+export function toCamelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}

package/dist/ontology-wire.d.ts

@@ -1,7 +1,10 @@
-import type { OntologyQuery, Where } from "./ontology.js";
+import type { Edit, OntologyQuery, Where } from "./ontology.js";
 interface CatalogProperty {
     readonly name: string;
     readonly type: string;
+    readonly options?: ReadonlyArray<{
+        readonly value: string;
+    }>;
 }
 interface CatalogRelationship {
     readonly name: string;
@@ -13,6 +16,22 @@ interface CatalogEntity {
     readonly name: string;
     readonly properties: ReadonlyArray<CatalogProperty>;
     readonly relationships: ReadonlyArray<CatalogRelationship>;
+    readonly actions?: ReadonlyArray<{
+        readonly name: string;
+        readonly input: JsonSchema;
+    }>;
+}
+interface JsonSchema {
+    readonly $ref?: string;
+    readonly $defs?: Readonly<Record<string, JsonSchema>>;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly items?: JsonSchema;
+    readonly anyOf?: ReadonlyArray<JsonSchema>;
+    readonly oneOf?: ReadonlyArray<JsonSchema>;
+    readonly enum?: ReadonlyArray<unknown>;
+    readonly const?: unknown;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly required?: ReadonlyArray<string>;
 }
 export interface WireCatalog {
     readonly hash?: string;
@@ -25,9 +44,14 @@ export declare function encodeWhere(input: {
     readonly getCatalog: () => Promise<WireCatalog>;
 }): Promise<Where | undefined>;
 export declare function queryToWire(query: OntologyQuery): unknown;
+/** Decode record fields and included relationships without descending into JSON properties. */
+export declare function recordFromWire<A = unknown>(value: unknown, entity: string, catalog: WireCatalog): A;
+export declare function actionInputToWire(input: unknown, entity: string, action: string, catalog: WireCatalog): unknown;
 export declare function responseFromWire(input: {
     readonly method: "GET" | "POST";
     readonly path: string;
     readonly payload: unknown;
 }): unknown;
+/** Decode current edits using the current catalog; stored historical changes retain their names. */
+export declare function editsFromWire(edits: ReadonlyArray<Edit>, catalog: WireCatalog): ReadonlyArray<Edit>;
 export {};

package/dist/ontology-wire.js

@@ -1,3 +1,4 @@
+import { toCamelCase, toSnakeCase } from "./ontology-names.js";
 const FILTER_OPERATORS = [
     "eq",
     "ne",
@@ -15,24 +16,10 @@ const SYSTEM_FIELDS = ["id", "created_at", "updated_at", "created_by", "updated_
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function needsOperatorEncoding(value) {
-    if (value === null || typeof value !== "object") {
-        return false;
-    }
-    for (const [key, child] of Object.entries(value)) {
-        if (key === "isNull" || key === "startsWith") {
-            return true;
-        }
-        if (needsOperatorEncoding(child)) {
-            return true;
-        }
-    }
-    return false;
-}
 /** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
 export async function encodeWhere(input) {
     const { where, entity, getCatalog } = input;
-    if (where === undefined || !needsOperatorEncoding(where)) {
+    if (where === undefined) {
         return where;
     }
     const catalog = await getCatalog();
@@ -52,12 +39,13 @@ function whereFromCatalog(input) {
             encodedWhere[field] = whereFromCatalog({ where: condition, entity, catalog });
             continue;
         }
-        const relationship = relationshipTarget({ field, entity, definition, catalog });
+        const wireField = toSnakeCase(field);
+        const relationship = relationshipTarget({ field: wireField, entity, definition, catalog });
         if (relationship !== undefined && isRecord(condition)) {
-            encodedWhere[field] = relationshipFilterToWire({ condition, relationship, catalog });
+            encodedWhere[wireField] = relationshipFilterToWire({ condition, relationship, catalog });
             continue;
         }
-        encodedWhere[field] = fieldFilterToWire({ field, condition, definition });
+        encodedWhere[wireField] = fieldFilterToWire({ field: wireField, condition, definition });
     }
     return encodedWhere;
 }
@@ -95,10 +83,10 @@ function isGeneratedField(field, definition) {
 }
 function fieldFilterToWire(input) {
     const { field, condition, definition } = input;
+    const property = definition?.properties.find((candidate) => candidate.name === field);
     if (!isRecord(condition)) {
-        return condition;
+        return selectToWire(condition, property);
     }
-    const property = definition?.properties.find((candidate) => candidate.name === field);
     if (property === undefined && !isGeneratedField(field, definition)) {
         return condition;
     }
@@ -108,7 +96,7 @@ function fieldFilterToWire(input) {
     }
     const encodedFilter = Object.create(null);
     for (const [operator, operand] of Object.entries(condition)) {
-        encodedFilter[operatorToWire(operator)] = operand;
+        encodedFilter[operatorToWire(operator)] = selectToWire(operand, property);
     }
     return encodedFilter;
 }
@@ -125,10 +113,136 @@ export function queryToWire(query) {
     const { orderBy, where, ...rest } = query;
     return {
         ...rest,
-        ...(orderBy === undefined ? {} : { order_by: orderBy }),
+        ...(orderBy === undefined
+            ? {}
+            : { order_by: orderBy.map((order) => ({ ...order, field: toSnakeCase(order.field) })) }),
+        ...(query.include === undefined
+            ? {}
+            : {
+                include: Object.fromEntries(Object.entries(query.include).map(([name, value]) => [toSnakeCase(name), value])),
+            }),
         ...(where === undefined ? {} : { where }),
     };
 }
+function selectToWire(value, property) {
+    if (property?.type !== "select") {
+        return value;
+    }
+    const convert = (child) => typeof child === "string" &&
+        property.options?.some((option) => option.value === toSnakeCase(child))
+        ? toSnakeCase(child)
+        : child;
+    return Array.isArray(value) ? value.map(convert) : convert(value);
+}
+/** Decode record fields and included relationships without descending into JSON properties. */
+export function recordFromWire(value, entity, catalog) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    const definition = catalog.entities.find((candidate) => candidate.name === entity);
+    return Object.fromEntries(Object.entries(value).map(([field, child]) => {
+        const property = definition?.properties.find((candidate) => candidate.name === field);
+        if (property?.type === "select" && typeof child === "string") {
+            return [toCamelCase(field), toCamelCase(child)];
+        }
+        const relationship = relationshipTarget({ field, entity, definition, catalog });
+        if (relationship !== undefined) {
+            const decoded = Array.isArray(child)
+                ? child.map((record) => recordFromWire(record, relationship.entity, catalog))
+                : recordFromWire(child, relationship.entity, catalog);
+            return [toCamelCase(field), decoded];
+        }
+        return [toCamelCase(field), child];
+    }));
+}
+function schemaInputToWire(value, schema, definitions) {
+    if (schema.$ref?.startsWith("#/$defs/")) {
+        const target = definitions[schema.$ref.slice("#/$defs/".length)];
+        return target === undefined ? value : schemaInputToWire(value, target, definitions);
+    }
+    const alternatives = schema.anyOf ?? schema.oneOf;
+    if (alternatives !== undefined) {
+        const object = alternatives.find((candidate) => matchesObjectSchema(value, candidate, definitions));
+        const array = alternatives.find((candidate) => candidate.items !== undefined && Array.isArray(value));
+        const literals = alternatives.flatMap((candidate) => candidate.enum ?? (candidate.const === undefined ? [] : [candidate.const]));
+        if (typeof value === "string" && literals.includes(toSnakeCase(value))) {
+            return toSnakeCase(value);
+        }
+        const target = object ?? array;
+        return target === undefined ? value : schemaInputToWire(value, target, definitions);
+    }
+    if (typeof value === "string" &&
+        (schema.enum?.includes(toSnakeCase(value)) || schema.const === toSnakeCase(value))) {
+        return toSnakeCase(value);
+    }
+    if (Array.isArray(value) && schema.items !== undefined) {
+        return value.map((child) => schemaInputToWire(child, schema.items, definitions));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    if (schema.properties === undefined) {
+        const childSchema = schema.additionalProperties;
+        return typeof childSchema === "object"
+            ? Object.fromEntries(Object.entries(value).map(([key, child]) => [
+                key,
+                schemaInputToWire(child, childSchema, definitions),
+            ]))
+            : value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([field, child]) => {
+        const wireField = toSnakeCase(field);
+        const childSchema = schema.properties?.[wireField];
+        return [
+            wireField,
+            childSchema === undefined ? child : schemaInputToWire(child, childSchema, definitions),
+        ];
+    }));
+}
+function matchesObjectSchema(value, schema, definitions) {
+    if (schema.$ref?.startsWith("#/$defs/")) {
+        const target = definitions[schema.$ref.slice("#/$defs/".length)];
+        return (target !== undefined && target !== schema && matchesObjectSchema(value, target, definitions));
+    }
+    if (!isRecord(value) || schema.properties === undefined) {
+        return false;
+    }
+    if (schema.required?.some((key) => !Object.hasOwn(value, key) && !Object.hasOwn(value, toCamelCase(key)))) {
+        return false;
+    }
+    return Object.entries(schema.properties).every(([key, childSchema]) => {
+        if (childSchema.const === undefined) {
+            return true;
+        }
+        const child = value[key] ?? value[toCamelCase(key)];
+        return (child === childSchema.const ||
+            (typeof child === "string" && toSnakeCase(child) === childSchema.const));
+    });
+}
+export function actionInputToWire(input, entity, action, catalog) {
+    const definition = catalog.entities.find((candidate) => candidate.name === entity);
+    const authored = definition?.actions?.find((candidate) => candidate.name === action);
+    if (authored !== undefined) {
+        return schemaInputToWire(input, authored.input, authored.input.$defs ?? {});
+    }
+    if (!isRecord(input)) {
+        return input;
+    }
+    return Object.fromEntries(Object.entries(input).map(([field, child]) => {
+        const wireField = toSnakeCase(field);
+        const property = definition?.properties.find((candidate) => candidate.name === wireField);
+        return [
+            wireField,
+            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),
+        ];
+    }));
+}
 function isPagedRoute(method, route) {
     if (route.endsWith("/history")) {
         return true;
@@ -159,3 +273,18 @@ export function responseFromWire(input) {
     const items = page.items.map(historyEntryFromWire);
     return { ...page, nextCursor, items };
 }
+/** Decode current edits using the current catalog; stored historical changes retain their names. */
+export function editsFromWire(edits, catalog) {
+    return edits.map((edit) => {
+        const before = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.before])), edit.entity, catalog);
+        const after = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.after])), edit.entity, catalog);
+        return {
+            ...edit,
+            entity: toCamelCase(edit.entity),
+            changes: Object.fromEntries(Object.keys(before).map((field) => [
+                field,
+                { before: before[field], after: after[field] },
+            ])),
+        };
+    });
+}

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;
@@ -222,7 +224,7 @@ export interface OntologyTransport {
 }
 /**
  * Entities and actions exist only in the app's types, so the client resolves them by name when
- * they are used: `ontology.lead.actions.change_status(…)` posts to `lead/actions/change_status`.
+ * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
 export declare function createOntologyClient<O>(transport: OntologyTransport, aggregateTransport?: OntologyTransport): OntologyClient<O>;
 /** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */

package/dist/ontology.js

@@ -1,7 +1,8 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
-import { encodeWhere, queryToWire, responseFromWire } from "./ontology-wire.js";
-const ENTITY_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
-const ACTION_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+import { actionInputToWire, encodeWhere, editsFromWire, queryToWire, recordFromWire, responseFromWire, } from "./ontology-wire.js";
+import { toCamelCase, toSnakeCase } from "./ontology-names.js";
+const ENTITY_NAME = /^[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*$/;
+const ACTION_NAME = ENTITY_NAME;
 /** Names a caller may probe on any object; never an entity or an action. */
 const RESERVED = new Set([
     "then",
@@ -18,7 +19,7 @@ const RESERVED = new Set([
 ]);
 /**
  * Entities and actions exist only in the app's types, so the client resolves them by name when
- * they are used: `ontology.lead.actions.change_status(…)` posts to `lead/actions/change_status`.
+ * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
 export function createOntologyClient(transport, aggregateTransport) {
     const entities = new Map();
@@ -31,12 +32,16 @@ export function createOntologyClient(transport, aggregateTransport) {
             let client = entities.get(property);
             if (client === undefined) {
                 client = {
-                    ...entityClient(property, catalogReader.transport, catalogReader.getCatalog),
+                    ...entityClient(toSnakeCase(property), catalogReader.transport, catalogReader.getCatalog),
                     aggregate: (request, options = {}) => {
                         if (!aggregateTransport) {
                             throw new TypeError("An aggregate transport is required.");
                         }
-                        return send(aggregateTransport, "POST", `/${property}/aggregate`, request, options.signal);
+                        return send(aggregateTransport, "POST", `/${toSnakeCase(property)}/aggregate`, aggregateToWire(request), options.signal).then((result) => ({
+                            ...result,
+                            fields: result.fields.map((field) => ({ ...field, name: toCamelCase(field.name) })),
+                            rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [toCamelCase(name), value]))),
+                        }));
                     },
                 };
                 entities.set(property, client);
@@ -79,12 +84,45 @@ function createCatalogReader(transport) {
 function entityClient(entity, transport, getCatalog) {
     const base = `/${entity}`;
     const actionCalls = new Map();
-    const runAction = (name, input, options = {}) => send(transport, "POST", `${base}/actions/${encodeURIComponent(name)}`, {
-        input,
-        ...(options.validateOnly === undefined
-            ? {}
-            : { options: { validate_only: options.validateOnly } }),
-    }, options.signal);
+    const runAction = async (name, input, options = {}) => {
+        const action = toSnakeCase(name);
+        const catalog = await getCatalog();
+        const wireResponse = await send(transport, "POST", `${base}/actions/${encodeURIComponent(action)}`, {
+            input: actionInputToWire(input, entity, action, catalog),
+            ...([options.validateOnly, options.idempotencyKey, options.createIntent].every((value) => value === undefined)
+                ? {}
+                : {
+                    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") {
+            return { ...response, result: recordFromWire(response.result, entity, catalog) };
+        }
+        if (action.startsWith("upsert_by_") &&
+            response.result !== null &&
+            typeof response.result === "object" &&
+            !Array.isArray(response.result)) {
+            return {
+                ...response,
+                result: {
+                    ...response.result,
+                    record: recordFromWire(response.result.record, entity, catalog),
+                },
+            };
+        }
+        return response;
+    };
     const actions = new Proxy(Object.create(null), {
         get(_target, property) {
             if (typeof property !== "string" || RESERVED.has(property) || !ACTION_NAME.test(property)) {
@@ -100,15 +138,28 @@ function entityClient(entity, transport, getCatalog) {
     });
     return {
         find: async (query = {}, options = {}) => {
+            const catalog = await getCatalog();
             const where = await encodeWhere({ where: query.where, entity, getCatalog });
             const search = findParameters({ ...query, where }).toString();
-            return send(transport, "GET", search === "" ? base : `${base}?${search}`, undefined, options.signal);
+            const page = await send(transport, "GET", search === "" ? base : `${base}?${search}`, undefined, options.signal);
+            return {
+                ...page,
+                items: page.items.map((record) => recordFromWire(record, entity, catalog)),
+            };
         },
         query: async (query = {}, options = {}) => {
+            const catalog = await getCatalog();
             const where = await encodeWhere({ where: query.where, entity, getCatalog });
-            return send(transport, "POST", `${base}/query`, queryToWire({ ...query, where }), options.signal);
+            const page = await send(transport, "POST", `${base}/query`, queryToWire({ ...query, where }), options.signal);
+            return {
+                ...page,
+                items: page.items.map((record) => recordFromWire(record, entity, catalog)),
+            };
+        },
+        get: (id, options = {}) => {
+            const encodedId = recordId(id);
+            return getCatalog().then(async (catalog) => recordFromWire(await send(transport, "GET", `${base}/${encodedId}`, undefined, options.signal), entity, catalog));
         },
-        get: (id, options = {}) => send(transport, "GET", `${base}/${recordId(id)}`, undefined, options.signal),
         history: (id, options = {}) => {
             const search = new URLSearchParams();
             if (options.after !== undefined) {
@@ -143,12 +194,14 @@ export function findParameters(query) {
         search.set("where", JSON.stringify(query.where));
     }
     if (query.orderBy !== undefined && query.orderBy.length > 0) {
-        search.set("order_by", query.orderBy.map(({ field, direction }) => `${field}:${direction ?? "asc"}`).join(","));
+        search.set("order_by", query.orderBy
+            .map(({ field, direction }) => `${toSnakeCase(field)}:${direction ?? "asc"}`)
+            .join(","));
     }
     if (query.include !== undefined) {
         const relationships = Object.keys(query.include).filter((name) => query.include?.[name] === true);
         if (relationships.length > 0) {
-            search.set("include", relationships.join(","));
+            search.set("include", relationships.map(toSnakeCase).join(","));
         }
     }
     if (query.after !== undefined) {
@@ -159,6 +212,34 @@ export function findParameters(query) {
     }
     return search;
 }
+/** The platform aggregate API keeps its existing protocol keys; ontology identifiers are canonical. */
+function aggregateToWire(request) {
+    return {
+        ...request,
+        dimensions: request.dimensions.map(toSnakeCase),
+        measures: request.measures.map(toSnakeCase),
+        ...(request.granularityOf === undefined
+            ? {}
+            : { granularityOf: toSnakeCase(request.granularityOf) }),
+        ...(request.filters === undefined
+            ? {}
+            : {
+                filters: request.filters.map((filter) => ({
+                    ...filter,
+                    dimension: toSnakeCase(filter.dimension),
+                })),
+            }),
+        ...(request.orderBy === undefined
+            ? {}
+            : {
+                orderBy: request.orderBy.map((order) => ({
+                    ...order,
+                    ...(order.dimension === undefined ? {} : { dimension: toSnakeCase(order.dimension) }),
+                    ...(order.measure === undefined ? {} : { measure: toSnakeCase(order.measure) }),
+                })),
+            }),
+    };
+}
 async function send(transport, method, path, body, signal) {
     const headers = new Headers({ accept: "application/json" });
     if (body !== undefined) {

package/dist/permissions.js

@@ -7,15 +7,18 @@
  * (`src/permissions.ts`) so that the app SDK and its browser components do not depend on the
  * ontology runtime. Keep the two in step.
  */
+import { toSnakeCase } from "./ontology-names.js";
 const WILDCARD = "*";
 /** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
+const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
 function parsePermission(value) {
     if (typeof value !== "string") {
         return undefined;
     }
     const match = PERMISSION.exec(value);
-    return match === null ? undefined : { entity: match[1], verb: match[2] };
+    return match === null
+        ? undefined
+        : { entity: toSnakeCase(match[1]), verb: toSnakeCase(match[2]) };
 }
 /** Whether a granted permission, which may hold wildcards, covers the required one. */
 export function grants(granted, required) {

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.6.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",