@segmentstream-cloud/app 0.5.0 → 0.7.0

package/README.md

@@ -1,5 +1,12 @@
 # @segmentstream-cloud/app
 
+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
 React 19. The app's users sign in with an email code, or a sign-in link the first time,
@@ -263,7 +270,9 @@ 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.changeStatus(input, { validateOnly: true });
+const check = await segmentstream.ontology.lead.actions.changeStatus(input, {
+  validateOnly: true,
+});
 const { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
 ```
 
@@ -272,7 +281,7 @@ const { result, validation, edits } = await segmentstream.ontology.lead.actions.
 - `actions.<name>(input, { validateOnly })` posts `{ input, options }` and returns
   `{ result, validation, edits }`. Generated actions are there too
   (`actions.create`, `update`, `delete`), and `action(name, input)` runs any action by
-  name, such as `upsertByEmail`.
+  name, such as `upsert_by_email`.
 - Failures throw `SegmentStreamApiError` with the service's `code` (`forbidden`,
   `not_found`, `invalid_input`, `action_rejected`, `conflict`, `not_invited`), `status`,
   `detail`, `requestId` and, for invalid input, `issues`.

package/dist/errors.js

@@ -35,7 +35,11 @@ export function apiErrorFrom(status, payload, fallbackDetail) {
         code: typeof body.error === "string" ? body.error : `http_${status}`,
         status,
         detail: typeof body.detail === "string" ? body.detail : fallbackDetail,
-        requestId: typeof body.requestId === "string" ? body.requestId : undefined,
+        requestId: typeof body.request_id === "string"
+            ? body.request_id
+            : typeof body.requestId === "string"
+                ? body.requestId
+                : undefined,
         retryable: typeof body.retryable === "boolean" ? body.retryable : status >= 500 || status === 429,
         issues: issuesFrom(body.issues),
     });

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

@@ -0,0 +1,57 @@
+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;
+    readonly to: string;
+    readonly inverse: string;
+    readonly cardinality: string;
+}
+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;
+    readonly entities: ReadonlyArray<CatalogEntity>;
+}
+/** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
+export declare function encodeWhere(input: {
+    readonly where: Where | undefined;
+    readonly entity: string;
+    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

@@ -0,0 +1,288 @@
+import { toCamelCase, toSnakeCase } from "./ontology-names.js";
+const FILTER_OPERATORS = [
+    "eq",
+    "ne",
+    "in",
+    "isNull",
+    "contains",
+    "startsWith",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+];
+const SYSTEM_FIELDS = ["id", "created_at", "updated_at", "created_by", "updated_by"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Catalog metadata distinguishes relationship filters from opaque JSON property values. */
+export async function encodeWhere(input) {
+    const { where, entity, getCatalog } = input;
+    if (where === undefined) {
+        return where;
+    }
+    const catalog = await getCatalog();
+    return whereFromCatalog({ where, entity, catalog });
+}
+function whereFromCatalog(input) {
+    const { where, entity, catalog } = input;
+    const definition = catalog.entities.find((candidate) => candidate.name === entity);
+    const encodedWhere = Object.create(null);
+    for (const [field, condition] of Object.entries(where)) {
+        if (field === "and" || field === "or") {
+            const conditions = condition;
+            encodedWhere[field] = conditions.map((child) => whereFromCatalog({ where: child, entity, catalog }));
+            continue;
+        }
+        if (field === "not") {
+            encodedWhere[field] = whereFromCatalog({ where: condition, entity, catalog });
+            continue;
+        }
+        const wireField = toSnakeCase(field);
+        const relationship = relationshipTarget({ field: wireField, entity, definition, catalog });
+        if (relationship !== undefined && isRecord(condition)) {
+            encodedWhere[wireField] = relationshipFilterToWire({ condition, relationship, catalog });
+            continue;
+        }
+        encodedWhere[wireField] = fieldFilterToWire({ field: wireField, condition, definition });
+    }
+    return encodedWhere;
+}
+function relationshipTarget(input) {
+    const { field, entity, definition, catalog } = input;
+    const forward = definition?.relationships.find((candidate) => candidate.name === field);
+    if (forward !== undefined) {
+        return { entity: forward.to, many: forward.cardinality === "many" };
+    }
+    for (const candidate of catalog.entities) {
+        const inverse = candidate.relationships.find((relationship) => relationship.to === entity && relationship.inverse === field);
+        if (inverse !== undefined) {
+            return { entity: candidate.name, many: true };
+        }
+    }
+    return undefined;
+}
+function relationshipFilterToWire(input) {
+    const { condition, relationship, catalog } = input;
+    const entity = relationship.entity;
+    if (!relationship.many) {
+        return whereFromCatalog({ where: condition, entity, catalog });
+    }
+    const encodedQuantifiers = Object.create(null);
+    for (const [quantifier, child] of Object.entries(condition)) {
+        encodedQuantifiers[quantifier] = whereFromCatalog({ where: child, entity, catalog });
+    }
+    return encodedQuantifiers;
+}
+function isGeneratedField(field, definition) {
+    if (SYSTEM_FIELDS.includes(field)) {
+        return true;
+    }
+    return (definition?.relationships.some((relationship) => relationship.cardinality === "one" && `${relationship.name}_id` === field) ?? false);
+}
+function fieldFilterToWire(input) {
+    const { field, condition, definition } = input;
+    const property = definition?.properties.find((candidate) => candidate.name === field);
+    if (!isRecord(condition)) {
+        return selectToWire(condition, property);
+    }
+    if (property === undefined && !isGeneratedField(field, definition)) {
+        return condition;
+    }
+    const operatorFilter = Object.keys(condition).every((operator) => FILTER_OPERATORS.includes(operator));
+    if (property?.type === "json" && !operatorFilter) {
+        return condition;
+    }
+    const encodedFilter = Object.create(null);
+    for (const [operator, operand] of Object.entries(condition)) {
+        encodedFilter[operatorToWire(operator)] = selectToWire(operand, property);
+    }
+    return encodedFilter;
+}
+function operatorToWire(operator) {
+    if (operator === "isNull") {
+        return "is_null";
+    }
+    if (operator === "startsWith") {
+        return "starts_with";
+    }
+    return operator;
+}
+export function queryToWire(query) {
+    const { orderBy, where, ...rest } = query;
+    return {
+        ...rest,
+        ...(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,
+            (action === "link" || action === "unlink") &&
+                field === "relationship" &&
+                typeof child === "string"
+                ? toSnakeCase(child)
+                : selectToWire(child, property),
+        ];
+    }));
+}
+function isPagedRoute(method, route) {
+    if (route.endsWith("/history")) {
+        return true;
+    }
+    if (method === "POST") {
+        return route.endsWith("/query");
+    }
+    const segments = route.split("/").filter(Boolean);
+    return segments.length === 1;
+}
+function historyEntryFromWire(item) {
+    const { record_id: recordId, action_id: actionId, principal_id: principalId, ...entry } = item;
+    return { ...entry, recordId, actionId, principalId };
+}
+export function responseFromWire(input) {
+    const { method, path, payload } = input;
+    if (!isRecord(payload)) {
+        return payload;
+    }
+    const route = path.split("?")[0] ?? "";
+    if (!isPagedRoute(method, route) || !Object.hasOwn(payload, "next_cursor")) {
+        return payload;
+    }
+    const { next_cursor: nextCursor, ...page } = payload;
+    if (!route.endsWith("/history") || !Array.isArray(page.items)) {
+        return { ...page, nextCursor };
+    }
+    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

@@ -222,7 +222,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.changeStatus(…)` posts to `lead/actions/changeStatus`.
+ * 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,6 +1,8 @@
 import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
-const ENTITY_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
-const ACTION_NAME = /^[a-z][a-zA-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",
@@ -17,10 +19,11 @@ 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.changeStatus(…)` posts to `lead/actions/changeStatus`.
+ * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
  */
 export function createOntologyClient(transport, aggregateTransport) {
     const entities = new Map();
+    const catalogReader = createCatalogReader(transport);
     return new Proxy(Object.create(null), {
         get(_target, property) {
             if (typeof property !== "string" || RESERVED.has(property) || !ENTITY_NAME.test(property)) {
@@ -29,11 +32,16 @@ export function createOntologyClient(transport, aggregateTransport) {
             let client = entities.get(property);
             if (client === undefined) {
                 client = {
-                    ...entityClient(property, transport),
+                    ...entityClient(toSnakeCase(property), catalogReader.transport, catalogReader.getCatalog),
                     aggregate: (request, options = {}) => {
-                        if (!aggregateTransport)
+                        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);
@@ -42,15 +50,67 @@ export function createOntologyClient(transport, aggregateTransport) {
         },
     });
 }
-function entityClient(entity, transport) {
+function createCatalogReader(transport) {
+    let catalogPromise;
+    let catalogHash;
+    const observedTransport = {
+        async fetch(path, init) {
+            const response = await transport.fetch(path, init);
+            const hash = response.headers.get("x-ontology-hash");
+            if (catalogHash !== undefined && hash !== null && hash !== catalogHash) {
+                catalogPromise = undefined;
+                catalogHash = undefined;
+            }
+            return response;
+        },
+    };
+    async function readCatalog() {
+        try {
+            const catalog = await send(observedTransport, "GET", "", undefined, undefined);
+            catalogHash = catalog.hash;
+            return catalog;
+        }
+        catch (error) {
+            catalogPromise = undefined;
+            throw error;
+        }
+    }
+    function getCatalog() {
+        catalogPromise ??= readCatalog();
+        return catalogPromise;
+    }
+    return { transport: observedTransport, getCatalog };
+}
+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: { validateOnly: 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 === undefined
+                ? {}
+                : { options: { validate_only: options.validateOnly } }),
+        }, 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)) {
@@ -65,12 +125,29 @@ function entityClient(entity, transport) {
         },
     });
     return {
-        find: (query = {}, options = {}) => {
-            const search = findParameters(query).toString();
-            return send(transport, "GET", search === "" ? base : `${base}?${search}`, undefined, options.signal);
+        find: async (query = {}, options = {}) => {
+            const catalog = await getCatalog();
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            const search = findParameters({ ...query, where }).toString();
+            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 });
+            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));
         },
-        query: (query = {}, options = {}) => send(transport, "POST", `${base}/query`, query, options.signal),
-        get: (id, options = {}) => send(transport, "GET", `${base}/${recordId(id)}`, undefined, options.signal),
         history: (id, options = {}) => {
             const search = new URLSearchParams();
             if (options.after !== undefined) {
@@ -105,12 +182,14 @@ export function findParameters(query) {
         search.set("where", JSON.stringify(query.where));
     }
     if (query.orderBy !== undefined && query.orderBy.length > 0) {
-        search.set("orderBy", 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) {
@@ -121,6 +200,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) {
@@ -144,5 +251,5 @@ async function send(transport, method, path, body, signal) {
             retryable: true,
         });
     }
-    return payload;
+    return responseFromWire({ method, path, payload });
 }

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 lower camelCase verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*)$/;
+/** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.5.0",
+  "version": "0.7.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",