@abloatai/transaction 0.52.0 → 0.54.0

package/src/transport/httpClient.ts

@@ -32,10 +32,12 @@ import type {
   HttpTransportModel,
   ModelReadOptions,
   ModelMutationOptions,
+  ModelList,
   CreateSessionParams,
   AbloSession,
   SessionResource,
 } from '../resources/httpResources.js';
+import { modelList } from '../resources/httpResources.js';
 import type {
   ModelCreateParams,
   ModelDeleteParams,
@@ -128,7 +130,12 @@ export interface HttpModelClient<T, C = T> {
    * Reads the rows matching a filter. Same resolution as `get`, in bulk,
    * and deduplicated so concurrent identical calls share one request.
    */
-  list(options?: ServerReadOptions<T>): Promise<CapturedRow<T>[]>;
+  /**
+   * The rows are an array as before; `hasMore` and `nextCursor` on the result
+   * say whether the collection continues past this page. Pass `nextCursor`
+   * back as `cursor`, with the same `where` and `orderBy`, to walk it.
+   */
+  list(options?: ServerReadOptions<T>): Promise<ModelList<CapturedRow<T>>>;
   /**
    * Creates a row and returns it, including any framework-applied defaults.
    * Passing an id that already exists is idempotent: the existing row is
@@ -427,10 +434,16 @@ function createHttpModelClient<T, C = T>(
     return read.data as CapturedRow<T> | undefined;
   };
 
-  const list = async (options?: ServerReadOptions<T>): Promise<CapturedRow<T>[]> => {
+  const list = async (
+    options?: ServerReadOptions<T>,
+  ): Promise<ModelList<CapturedRow<T>>> => {
     const snapshot = await protocol.list(options);
+    const page = modelList<CapturedRow<T>>(
+      snapshot.data as readonly CapturedRow<T>[],
+      snapshot,
+    );
     const registry = readSetContext?.getStore();
-    if (!registry) return [...snapshot.data] as CapturedRow<T>[];
+    if (!registry) return page;
     if (!snapshot.evidence) {
       throw new AbloConnectionError(
         `${modelName}.list did not return row evidence. Upgrade the Ablo server or use get({ id }).`,
@@ -451,7 +464,7 @@ function createHttpModelClient<T, C = T>(
       }
       capturePointRead(readSetContext, clientIdentity, modelName, id, row, stamp);
     }
-    return [...snapshot.data] as CapturedRow<T>[];
+    return page;
   };
 
   // Claim acquisition performs its authoritative read only after the grant.

package/src/transport/httpTransport.ts

@@ -84,6 +84,7 @@ import type {
   ModelMutationOptions,
   ModelReadOptions,
   HttpTransportRead,
+  HttpTransportList,
   HttpLogsResource,
   ModelTarget,
   CreateSessionParams,
@@ -151,6 +152,7 @@ import { declaredMeta, wireMeta } from '../coordination/claimMeta.js';
 import type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim } from '../types/streams.js';
 import type { CoordinationObservability } from '../observability.js';
 import { assertWriteOptions } from '../resources/writeOptionsSchema.js';
+import { normalizeWhere } from '../resources/where.js';
 import {
   createDurableHttpCommitEnvelope,
   canonicalHttpCommitBody,
@@ -1493,9 +1495,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   async function listModel<T>(
     modelName: string,
     options?: ServerReadOptions<T>,
-  ): Promise<{ readonly data: readonly T[]; readonly evidence?: readonly { id: string; stamp: number }[] }> {
+  ): Promise<HttpTransportList<T>> {
     const params = new URLSearchParams();
     if (options?.limit !== undefined) params.set('limit', String(options.limit));
+    if (options?.cursor !== undefined) {
+      params.set('cursor', options.cursor);
+    }
     if (options?.orderBy) {
       const [col, dir] = Object.entries(options.orderBy)[0] ?? [];
       if (col) {
@@ -1503,12 +1508,27 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         if (dir === 'desc') params.set('order', 'desc');
       }
     }
-    // The collection route turns any non-reserved query param into an equality
-    // filter (`?status=todo`). The wire is AND-only equality — matches what a
-    // stateless reactor needs; richer predicates stay on the stateful path.
-    if (options?.where && typeof options.where === 'object') {
-      for (const [k, v] of Object.entries(options.where as Record<string, unknown>)) {
-        if (v !== undefined && v !== null && typeof v !== 'object') params.set(k, String(v));
+    // The whole filter travels as the canonical clause list, so every operator
+    // the grammar declares survives the trip. The previous encoding walked the
+    // object's own entries and skipped any value that was an object, which
+    // silently discarded `IN` filters and every tuple-form clause: the request
+    // went out unfiltered and the caller read the result as a filtered one.
+    const clauses = normalizeWhere(options?.where);
+    if (clauses.length > 0) {
+      params.set('where', JSON.stringify(clauses));
+      // Plain equality also goes out in the older `?column=value` shorthand.
+      // A server that predates the `where` parameter does not reserve the name
+      // and does not declare it as a column, so it skips it — and a dropped
+      // filter is not an error there, it is a wider answer than the caller
+      // asked for. Sending both means a version skew loses only the operator
+      // filters, which that server could not have honoured anyway. A current
+      // server ignores a shorthand key the clause list already carries.
+      for (const clause of clauses) {
+        const [column] = clause;
+        const value = clause.length === 2 ? clause[1] : clause[2];
+        if (clause.length === 3 && clause[1] !== '=') continue;
+        if (value === null || typeof value === 'object') continue;
+        params.set(column, String(value));
       }
     }
     const qs = params.toString();
@@ -1523,6 +1543,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     // the typed facade above, which holds the model's schema.
     return {
       data: res.data as T[],
+      hasMore: res.has_more,
+      nextCursor: res.next_cursor,
       ...(res.evidence ? { evidence: res.evidence } : {}),
     };
   }

package/src/wire/accountResponses.ts

@@ -14,6 +14,7 @@
  */
 
 import { z } from 'zod';
+import { listEnvelopeSchema } from './listEnvelope.js';
 // Composed, never restated: these are the artifact's own shapes, and a
 // hand-written mirror here would be a second copy of the exact record this
 // response exists to stop withholding.
@@ -45,16 +46,9 @@ export type ProjectResponse = z.infer<typeof projectResponseSchema>;
 /**
  * `GET /v1/projects`.
  *
- * Note what this is NOT: the canonical {@link ListEnvelope}. An org's projects
- * are returned whole, so the route emits `data` with no `has_more`/`next_cursor`
- * beside it. That divergence is real and this schema states it rather than
- * describing a pagination the endpoint does not implement — adding the two
- * fields is an API change, not a documentation fix.
+ * Uses the canonical paginated list envelope shared by every collection.
  */
-export const projectListResponseSchema = z.object({
-  object: z.literal('list'),
-  data: z.array(projectResponseSchema).readonly(),
-});
+export const projectListResponseSchema = listEnvelopeSchema(projectResponseSchema);
 export type ProjectListResponse = z.infer<typeof projectListResponseSchema>;
 
 /** One minted key, returned exactly once — the plaintext is never readable again. */

package/src/wire/auth.ts

@@ -27,7 +27,7 @@ export type EphemeralKeyUser = z.infer<typeof ephemeralKeyUserSchema>;
  * Only a secret key (`sk_`) may call this: a session cannot mint itself. By
  * default the key mints into the caller's own organization; naming a different
  * `organizationId` is the multi-tenant case and requires the
- * `ephemeral:mint-any-org` scope, which is the same privilege that allows
+ * `organization:act-as` scope, which is the same privilege that allows
  * binding the session's schema to another organization's project.
  */
 export const ephemeralKeyRequestSchema = z.object({
@@ -35,7 +35,7 @@ export const ephemeralKeyRequestSchema = z.object({
   user: ephemeralKeyUserSchema,
   /**
    * Mint into this organization instead of the caller's own. Requires the
-   * `ephemeral:mint-any-org` scope — without it a secret key can never mint a
+   * `organization:act-as` scope — without it a secret key can never mint a
    * session into another tenant.
    */
   organizationId: z.string().min(1).optional(),
@@ -43,7 +43,7 @@ export const ephemeralKeyRequestSchema = z.object({
    * Override the shared project used to resolve this session's schema while
    * its data stays scoped to the target organization. A cross-organization
    * mint defaults both coordinates to the caller key's own project. Both
-   * fields are set together, and both require `ephemeral:mint-any-org`.
+   * fields are set together, and both require `organization:act-as`.
    */
   schemaProjectId: z.string().min(1).optional(),
   schemaOwnerOrgId: z.string().min(1).optional(),

package/src/wire/claims.ts

@@ -121,7 +121,13 @@ export const listQuerySchema = z.object({
   limit: z.string().optional(),
   order_by: z.string().optional(),
   order: z.enum(['asc', 'desc']).optional(),
-  /** Keyset cursor: the id of the last row from the previous page. */
+  /**
+   * Keyset cursor: the opaque `next_cursor` the previous page returned. It
+   * encodes the sort position it was issued for, so it is not a row id and is
+   * refused against a different `order_by`/`order`.
+   */
+  cursor: z.string().optional(),
+  /** @deprecated The pre-0.53.0 spelling of `cursor`. Send `cursor`. */
   starting_after: z.string().optional(),
 });
 export type ListQuery = z.infer<typeof listQuerySchema>;

package/src/wire/index.ts

@@ -22,7 +22,13 @@ export {
   INTERNAL_ERROR_PUBLIC_MESSAGE,
 } from './errorEnvelope.js';
 export type { ErrorEnvelope } from './errorEnvelope.js';
-export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+export {
+  listEnvelopeSchema,
+  listEnvelope,
+  CURSOR_PARAM,
+  CURSOR_PARAM_ALIAS,
+  CURSOR_PARAM_NAMES,
+} from './listEnvelope.js';
 export type { ListEnvelope } from './listEnvelope.js';
 
 // The `GET /v1/logs` feed — the two arms, their envelope, and the cursor that

package/src/wire/listEnvelope.ts

@@ -10,6 +10,29 @@
  */
 import { z } from 'zod';
 
+/**
+ * The query parameter a caller resumes a collection with, and the single alias
+ * retained for it.
+ *
+ * Declared beside the envelope that issues `next_cursor`, because the parameter
+ * and the field it consumes are one contract and both planes read them: the
+ * server to know which names are taken, the spec generator to document them,
+ * the client to send one. When the name lived in each of those separately, this
+ * spec described `starting_after` for a model list and `cursor` for a commit
+ * record list — the same concept under two names, in one document.
+ *
+ * `starting_after` is the spelling used through 0.52.0. It borrowed a name whose
+ * established meaning elsewhere is a row id, while this value has always been an
+ * opaque token bound to the sort it was issued for.
+ */
+export const CURSOR_PARAM = 'cursor';
+
+/** @deprecated The pre-0.53.0 spelling of {@link CURSOR_PARAM}. */
+export const CURSOR_PARAM_ALIAS = 'starting_after';
+
+/** Both names a cursor may arrive under, for reserving them in a query string. */
+export const CURSOR_PARAM_NAMES: readonly string[] = [CURSOR_PARAM, CURSOR_PARAM_ALIAS];
+
 /**
  * Builds the authoritative list-envelope schema for a row schema. Keeping the
  * item validator generic lets every endpoint share the same envelope contract