@segmentstream-cloud/app 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +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.
+
 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,
@@ -111,7 +117,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:changeStatus")` is `true` when the user's permissions cover the
+- `can("lead:change_status")` 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
@@ -126,22 +132,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: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                 |
+| 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                 |
 
 `<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:changeStatus" fallback={lead.status}>
+<Can permission="lead:change_status" fallback={lead.status}>
   <ChangeStatusForm lead={lead.id} />
 </Can>
 ```
@@ -254,7 +260,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: "createdAt", direction: "desc" }],
+  orderBy: [{ field: "created_at", direction: "desc" }],
   include: { owner: true },
   limit: 20,
 });
@@ -263,8 +269,11 @@ 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 { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
+const check = await segmentstream.ontology.lead.actions.change_status(input, {
+  validateOnly: true,
+});
+const { result, validation, edits } =
+  await segmentstream.ontology.lead.actions.change_status(input);
 ```
 
 - `find` sends the query as URL parameters, `query` as a JSON body; both return
@@ -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/ontology-wire.d.ts

@@ -0,0 +1,33 @@
+import type { OntologyQuery, Where } from "./ontology.js";
+interface CatalogProperty {
+    readonly name: string;
+    readonly type: 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>;
+}
+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;
+export declare function responseFromWire(input: {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly payload: unknown;
+}): unknown;
+export {};

package/dist/ontology-wire.js

@@ -0,0 +1,161 @@
+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);
+}
+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)) {
+        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 relationship = relationshipTarget({ field, entity, definition, catalog });
+        if (relationship !== undefined && isRecord(condition)) {
+            encodedWhere[field] = relationshipFilterToWire({ condition, relationship, catalog });
+            continue;
+        }
+        encodedWhere[field] = fieldFilterToWire({ field, 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;
+    if (!isRecord(condition)) {
+        return condition;
+    }
+    const property = definition?.properties.find((candidate) => candidate.name === field);
+    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)] = operand;
+    }
+    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 }),
+        ...(where === undefined ? {} : { where }),
+    };
+}
+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 };
+}

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.change_status(…)` 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,7 @@
 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-zA-Z0-9]*$/;
+const ACTION_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
 /** Names a caller may probe on any object; never an entity or an action. */
 const RESERVED = new Set([
     "then",
@@ -17,10 +18,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.change_status(…)` 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,10 +31,11 @@ export function createOntologyClient(transport, aggregateTransport) {
             let client = entities.get(property);
             if (client === undefined) {
                 client = {
-                    ...entityClient(property, transport),
+                    ...entityClient(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);
                     },
                 };
@@ -42,14 +45,45 @@ 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: { validate_only: options.validateOnly } }),
     }, options.signal);
     const actions = new Proxy(Object.create(null), {
         get(_target, property) {
@@ -65,11 +99,15 @@ function entityClient(entity, transport) {
         },
     });
     return {
-        find: (query = {}, options = {}) => {
-            const search = findParameters(query).toString();
+        find: async (query = {}, options = {}) => {
+            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);
         },
-        query: (query = {}, options = {}) => send(transport, "POST", `${base}/query`, query, options.signal),
+        query: async (query = {}, options = {}) => {
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            return send(transport, "POST", `${base}/query`, queryToWire({ ...query, where }), options.signal);
+        },
         get: (id, options = {}) => send(transport, "GET", `${base}/${recordId(id)}`, undefined, options.signal),
         history: (id, options = {}) => {
             const search = new URLSearchParams();
@@ -105,7 +143,7 @@ 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 }) => `${field}:${direction ?? "asc"}`).join(","));
     }
     if (query.include !== undefined) {
         const relationships = Object.keys(query.include).filter((name) => query.include?.[name] === true);
@@ -144,5 +182,5 @@ async function send(transport, method, path, body, signal) {
             retryable: true,
         });
     }
-    return payload;
+    return responseFromWire({ method, path, payload });
 }

package/dist/permissions.js

@@ -8,8 +8,8 @@
  * ontology runtime. Keep the two in step.
  */
 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-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
 function parsePermission(value) {
     if (typeof value !== "string") {
         return undefined;

package/package.json

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