@vxil/sdk 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -414,8 +414,10 @@ export interface JobRun {
     concurrency_limit?: number | null;
     /** the fan-in batch the run joined (enqueue `batch_id`); null otherwise */
     batch_id?: string | null;
-    /** a plain run enqueued with `ttl_seconds`: its START deadline (it is
-     *  dead-lettered `Expired` if not started by then); null otherwise */
+    /** the run's deadline. A plain run enqueued with `ttl_seconds`: its START
+     *  deadline (dead-lettered `Expired` if not started by then). A generation
+     *  run: its completion deadline (`timeout.after_ms`; past it the run ends
+     *  `GenerationExpired` and any credit hold is released). Null otherwise. */
     expires_at?: string | null;
     /** the single-run read only: the debounce key of a debounced run */
     debounce_key?: string | null;
@@ -2264,6 +2266,11 @@ type DisabledFeatures<S extends VxilSchemaShape> = {
 export type EnabledVxil<S extends VxilSchemaShape> = Omit<Vxil<S>, DisabledFeatures<S>> & {
     [P in DisabledFeatures<S>]: DisabledFeature<FeatureMap[P] & string>;
 };
+/** A cms collection's END-USER ACCESS mode (guide ch. 9): what a verified end
+ *  user (thin-client key + session) may do on it — `'readwrite'` (default),
+ *  `'read'` (writes are `403 server_only`) or `'none'` (reads and writes are
+ *  `403 server_only`). Server keys are never affected. */
+export type CmsEndUserAccess = 'readwrite' | 'read' | 'none';
 /** One config-declared per-record ACTION (guide ch. 4): a button on a record row
  *  that invokes the deployed tenant function `fn` ONCE with `{ collection,
  *  item_id, action, actor, item }`. Exactly one human-initiated step — no
@@ -3279,7 +3286,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
             /** `progress_fields`: the progress keys (`progress` / `stage` /
              *  `message`) a webhook-mode `processing` callback also writes onto the
-             *  mirrored record — realtime clients of that record see them live */
+             *  mirrored record — realtime clients of that record see them live.
+             *  In END-USER mode (`asEndUser`, or a function invoked for a signed-in
+             *  user) the target must be a cms record that user can read: another
+             *  user's row, a server-only collection or a non-cms feature answers
+             *  403 `mirror_target_forbidden` and nothing starts (503
+             *  `mirror_check_unavailable` if the check could not run — retry).
+             *  Mirror onto a server-only row from server-mode code instead. */
             status_mirror?: {
                 feature: string;
                 collection: string;
@@ -3931,7 +3944,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     };
     readonly cms: {
         collections: {
-            /** Define a content type. The model is data — not config. */
+            /** Define a content type. The model is data — not config.
+             *  Model management (`create`, `addField` and every fields-route meta-op
+             *  in this namespace) is SERVER-ONLY: a client acting as a signed-in end
+             *  user (`asEndUser`, a thin-client key) gets `403 server_only`. Call
+             *  these with a server key — your backend, `vxil push`, or the dashboard. */
             create: (input: {
                 collection: string;
                 singular?: string;
@@ -3947,6 +3964,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  and the owner_field are never exposed. Optional; defaults false. Use the
                  *  top-level `cmsPublicUrl` / `listCmsPublic` helpers for the reader side. */
                 public?: boolean;
+                /** What a VERIFIED end user may do here (guide ch. 9, "Read-only and
+                 *  server-only collections"): `'readwrite'` (default), `'read'` (every
+                 *  end-user write is `403 server_only`; reads unchanged) or `'none'`
+                 *  (end-user reads and writes are `403 server_only`, even with an
+                 *  owner_field). Server keys are never affected. */
+                end_user_access?: CmsEndUserAccess;
                 fields?: Array<{
                     field: string;
                     type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -3994,12 +4017,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string;
                 public?: boolean;
                 actions?: CmsActionDef[];
+                /** present when not the default 'readwrite' */
+                end_user_access?: CmsEndUserAccess;
             }>;
             list: () => Promise<Array<{
                 collection: string;
                 singular: string;
                 fields: unknown[];
                 owner_field?: string | null;
+                /** the collection's end-user access mode (absent from an older server = 'readwrite') */
+                end_user_access?: CmsEndUserAccess;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
             /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4031,6 +4058,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the owner_field are never exposed. `false` closes the lane (and purges the
              *  edge cache). Read the public side with `cmsPublicUrl` / `listCmsPublic`. */
             setPublic: (collection: string, isPublic: boolean) => Promise<void>;
+            /** Set the collection's END-USER ACCESS mode (guide ch. 9, "Read-only and
+             *  server-only collections"). `'read'`: a verified end user (thin-client
+             *  key + session) may still read — owner-scoped when the collection has an
+             *  owner_field — but every end-user write answers `403 server_only`;
+             *  `'none'`: end-user reads and writes are both refused; `'readwrite'`
+             *  (default) restores today's behaviour. Server keys are never affected.
+             *  Audited; takes effect on the next request. */
+            setEndUserAccess: (collection: string, access: CmsEndUserAccess) => Promise<{
+                collection: string;
+                end_user_access: CmsEndUserAccess;
+            }>;
             /** Re-project the collection's index slots after an `index_slot` move
              *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the

package/dist/index.js

@@ -1210,7 +1210,11 @@ export class Vxil {
     };
     cms = {
         collections: {
-            /** Define a content type. The model is data — not config. */
+            /** Define a content type. The model is data — not config.
+             *  Model management (`create`, `addField` and every fields-route meta-op
+             *  in this namespace) is SERVER-ONLY: a client acting as a signed-in end
+             *  user (`asEndUser`, a thin-client key) gets `403 server_only`. Call
+             *  these with a server key — your backend, `vxil push`, or the dashboard. */
             create: async (input) => (await this.call('POST', '/v1/cms/collections', input)).data,
             list: async () => (await this.call('GET', '/v1/cms/collections')).data.collections,
             addField: async (collection, field) => {
@@ -1262,6 +1266,14 @@ export class Vxil {
             setPublic: async (collection, isPublic) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
             },
+            /** Set the collection's END-USER ACCESS mode (guide ch. 9, "Read-only and
+             *  server-only collections"). `'read'`: a verified end user (thin-client
+             *  key + session) may still read — owner-scoped when the collection has an
+             *  owner_field — but every end-user write answers `403 server_only`;
+             *  `'none'`: end-user reads and writes are both refused; `'readwrite'`
+             *  (default) restores today's behaviour. Server keys are never affected.
+             *  Audited; takes effect on the next request. */
+            setEndUserAccess: async (collection, access) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { end_user_access: access })).data,
             /** Re-project the collection's index slots after an `index_slot` move
              *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",