@substrat-run/contracts 0.39.0 → 0.40.0

package/dist/connections.d.ts

@@ -13,11 +13,16 @@ export type ConnectionStatus = z.infer<typeof connectionStatus>;
 /**
  * A connection as the directory holds it.
  *
- * Keyed on **(tenant, vertical, provider)** rather than tenant alone
+ * Keyed on **(tenant, vertical, provider, account)** rather than tenant alone
  * (connections.md §3.1.1): a vertical is a blast-radius boundary (D-30) and
  * verticals are built by different companies (D-33), so one vendor's host code
  * must not reach a credential another vendor connected. It also matches how
  * OAuth issues clients — two vendors acting for one tenant hold two clients.
+ * The account leg is `externalAccountRef` (Vercel's "Git namespace" shape): one
+ * tenant may hold the SAME provider under several external accounts — two
+ * GitHub orgs, say — and each is its own connection. Providers that never set
+ * an account ref collapse back to one live connection per (tenant, vertical,
+ * provider), the pre-#101-widening behavior.
  */
 export declare const connection: z.ZodObject<{
     id: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
@@ -71,6 +76,7 @@ export declare const connectionFilter: z.ZodObject<{
     tenantId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TenantId", "out">>;
     vertical: z.ZodOptional<z.ZodString>;
     provider: z.ZodOptional<z.ZodString>;
+    externalAccountRef: z.ZodOptional<z.ZodString>;
     includeRevoked: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ConnectionFilter = z.infer<typeof connectionFilter>;

package/dist/connections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,eAAO,MAAM,YAAY,wDAAiD,CAAC;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,aAIiC,CAAC;AAEjE,eAAO,MAAM,gBAAgB;;;;;EAS3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;iBA0BrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,uCAA0C,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB;;;;;;;;;;;iBAmBhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,gBAAgB;;;;;iBAM3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,YAAY,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,eAAO,MAAM,YAAY,wDAAiD,CAAC;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,aAIiC,CAAC;AAEjE,eAAO,MAAM,gBAAgB;;;;;EAS3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;iBA0BrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,uCAA0C,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB;;;;;;;;;;;iBAmBhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,gBAAgB;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,YAAY,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/connections.js

@@ -29,11 +29,16 @@ export const connectionStatus = z.enum([
 /**
  * A connection as the directory holds it.
  *
- * Keyed on **(tenant, vertical, provider)** rather than tenant alone
+ * Keyed on **(tenant, vertical, provider, account)** rather than tenant alone
  * (connections.md §3.1.1): a vertical is a blast-radius boundary (D-30) and
  * verticals are built by different companies (D-33), so one vendor's host code
  * must not reach a credential another vendor connected. It also matches how
  * OAuth issues clients — two vendors acting for one tenant hold two clients.
+ * The account leg is `externalAccountRef` (Vercel's "Git namespace" shape): one
+ * tenant may hold the SAME provider under several external accounts — two
+ * GitHub orgs, say — and each is its own connection. Providers that never set
+ * an account ref collapse back to one live connection per (tenant, vertical,
+ * provider), the pre-#101-widening behavior.
  */
 export const connection = z.object({
     id: connectionId,
@@ -97,6 +102,8 @@ export const connectionFilter = z.object({
     tenantId: tenantId.optional(),
     vertical: z.string().min(1).optional(),
     provider: connectionProvider.optional(),
+    /** Narrow to one external account — the multi-namespace provider's selector. */
+    externalAccountRef: z.string().optional(),
     /** Revoked connections are evidence, not roster — excluded unless asked for. */
     includeRevoked: z.boolean().optional(),
 });

package/dist/connections.js.map

@@ -1 +1 @@
-{"version":3,"file":"connections.js","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from './registry.js';
 export * from './routing.js';
 export * from './tenancy.js';
 export * from './introspection.js';
+export * from './pagination.js';
 export * from './connections.js';
 export * from './control-plane.js';
 export * from './permission.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -22,6 +22,7 @@ export * from './registry.js';
 export * from './routing.js';
 export * from './tenancy.js';
 export * from './introspection.js';
+export * from './pagination.js';
 export * from './connections.js';
 export * from './control-plane.js';
 export * from './permission.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/pagination.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * The ONE pagination convention for every list read on the platform (#458-shape
+ * work): keyset ("cursor") pages over the list's own sort key, `{ entries,
+ * nextCursor }` out. Grown from the admin-log read (`AuditLogFilter` /
+ * `GET /admin-log`), which shipped it first; everything else now follows.
+ *
+ * Two layers, deliberately different defaults (the admin-log precedent):
+ * - **Kernel/adapter reads** (`HostAdmin.list*`) take an optional `ListPage`;
+ *   unset means UNBOUNDED, because internal callers (provisioning, catalogs,
+ *   sweeps) mean "everything" and a silent cap would let them mistake a page
+ *   for the whole set.
+ * - **HTTP list routes** DEFAULT a page (`LIST_PAGE_DEFAULT`) — the egress is
+ *   where an ever-growing table must stop being a dump. UIs walk with `cursor`.
+ *
+ * The cursor is the last entry's sort key verbatim (ULID id, slug, hostname…)
+ * — chronological where the key is a ULID, lexicographic otherwise — so it
+ * needs no encoding and survives in a query string. A composite sort key joins
+ * its parts with `|` (first part always `|`-free: a ULID or enum).
+ */
+/** Default page size on every HTTP list read. */
+export declare const LIST_PAGE_DEFAULT = 20;
+/** Hard ceiling on a requested page — same order as a table page (§ introspection). */
+export declare const LIST_PAGE_MAX = 200;
+/**
+ * Query-string shape of every paged HTTP list read. `order` flips the walk
+ * direction where the route supports it (each route documents its default —
+ * existing routes keep the order they shipped with).
+ */
+export declare const listPageQuery: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+export type ListPageQuery = z.infer<typeof listPageQuery>;
+/**
+ * Kernel-side page params, foldable into any list filter. Unset `limit` means
+ * unbounded (see above). `cursor` is exclusive: entries strictly after it in
+ * `asc` order, strictly before it in `desc`.
+ */
+export interface ListPage {
+    limit?: number;
+    cursor?: string;
+    order?: 'asc' | 'desc';
+}
+/** The envelope every paged HTTP list read returns. */
+export interface Page<T> {
+    entries: T[];
+    nextCursor: string | null;
+}
+/**
+ * Wrap a just-read page. `nextCursor` is the last entry's sort key when the
+ * page came back full (there MAY be more), null when it came back short (the
+ * walk is done — no trailing empty fetch).
+ */
+export declare function pageOf<T>(entries: T[], limit: number, key: (entry: T) => string): Page<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,uFAAuF;AACvF,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;iBAIxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAGzF"}

package/dist/pagination.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/**
+ * The ONE pagination convention for every list read on the platform (#458-shape
+ * work): keyset ("cursor") pages over the list's own sort key, `{ entries,
+ * nextCursor }` out. Grown from the admin-log read (`AuditLogFilter` /
+ * `GET /admin-log`), which shipped it first; everything else now follows.
+ *
+ * Two layers, deliberately different defaults (the admin-log precedent):
+ * - **Kernel/adapter reads** (`HostAdmin.list*`) take an optional `ListPage`;
+ *   unset means UNBOUNDED, because internal callers (provisioning, catalogs,
+ *   sweeps) mean "everything" and a silent cap would let them mistake a page
+ *   for the whole set.
+ * - **HTTP list routes** DEFAULT a page (`LIST_PAGE_DEFAULT`) — the egress is
+ *   where an ever-growing table must stop being a dump. UIs walk with `cursor`.
+ *
+ * The cursor is the last entry's sort key verbatim (ULID id, slug, hostname…)
+ * — chronological where the key is a ULID, lexicographic otherwise — so it
+ * needs no encoding and survives in a query string. A composite sort key joins
+ * its parts with `|` (first part always `|`-free: a ULID or enum).
+ */
+/** Default page size on every HTTP list read. */
+export const LIST_PAGE_DEFAULT = 20;
+/** Hard ceiling on a requested page — same order as a table page (§ introspection). */
+export const LIST_PAGE_MAX = 200;
+/**
+ * Query-string shape of every paged HTTP list read. `order` flips the walk
+ * direction where the route supports it (each route documents its default —
+ * existing routes keep the order they shipped with).
+ */
+export const listPageQuery = z.object({
+    limit: z.coerce.number().int().positive().max(LIST_PAGE_MAX).default(LIST_PAGE_DEFAULT),
+    cursor: z.string().min(1).optional(),
+    order: z.enum(['asc', 'desc']).optional(),
+});
+/**
+ * Wrap a just-read page. `nextCursor` is the last entry's sort key when the
+ * page came back full (there MAY be more), null when it came back short (the
+ * walk is done — no trailing empty fetch).
+ */
+export function pageOf(entries, limit, key) {
+    const last = entries.length >= limit ? entries[entries.length - 1] : undefined;
+    return { entries, nextCursor: last === undefined ? null : key(last) };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iDAAiD;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,uFAAuF;AACvF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IACvF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAoBH;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAI,OAAY,EAAE,KAAa,EAAE,GAAyB;IAC9E,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {