@vxil/sdk 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -1999,6 +1999,12 @@ export interface CmsReindexPage {
     skipped: number;
     next_cursor: string | null;
     complete: boolean;
+    /** Present when this page certified an index (the last page of a pass over
+     *  a collection whose equality / owner index was not armed): 'armed',
+     *  'pending' (rows changed during the pass — run another) or 'timeout' (the
+     *  check ran out of time — the index stays unarmed; filters stay correct
+     *  but unaccelerated). */
+    index_certify?: 'armed' | 'pending' | 'timeout';
 }
 /** The result of a bounded filtered delete (cms.md §20). `matched` counts the
  *  rows this page selected (≤ `limit`); `deleted` counts the ones actually
@@ -3569,6 +3575,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                      *  session) still sees every field. Writes are unaffected. ≤16 entries,
                      *  each `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
                     read_roles?: string[];
+                    /** Equality index for an UNSLOTTED field (cms.md §3 "Indexed
+                     *  equality"): `=` / `$eq` / `$in` filters on it are index-served
+                     *  instead of a bounded scan — results are identical either way. ≤4
+                     *  per collection; not with `index_slot` (a slot already indexes
+                     *  equality) and not on a computed field. */
+                    indexed?: boolean;
                 }>;
                 /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]` —
                  *  exactly ONE human-initiated step each; `fn` names a deployed tenant
@@ -3596,6 +3608,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  read unless the session's verified roles intersect `roles`; server-caller
              *  reads and ALL writes are unaffected. */
             setFieldReadRoles: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", roles: string[] | null, rest?: Record<string, unknown>) => Promise<void>;
+            /** Turn a field's EQUALITY INDEX on or off (cms.md §3 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", indexed: boolean) => Promise<{
+                indexed: boolean;
+                index_ready: boolean;
+                reindex_required: boolean;
+            }>;
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
              *  (design §5.1). Names an existing `string` field that holds the owner id. */
             setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
@@ -3633,6 +3657,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 updated: number;
                 skipped: number;
                 pages: number;
+                index_certify?: CmsReindexPage["index_certify"];
             }>;
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE

package/dist/index.js

@@ -1088,6 +1088,29 @@ export class Vxil {
             setFieldReadRoles: async (collection, field, type, roles, rest = {}) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { ...rest, field, type, read_roles: roles ?? [] });
             },
+            /** Turn a field's EQUALITY INDEX on or off (cms.md §3 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: async (collection, field, type, indexed) => {
+                try {
+                    const d = (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { field, type, indexed })).data ?? {};
+                    return { indexed: d.indexed ?? indexed, index_ready: d.index_ready ?? indexed, reindex_required: d.reindex_required === true };
+                }
+                catch (e) {
+                    // 409 already_exists = the field is already in that state (the
+                    // idempotent re-POST); read its readiness from the collection list.
+                    if (!(e instanceof VxilError) || e.status !== 409)
+                        throw e;
+                    const colls = (await this.call('GET', '/v1/cms/collections')).data.collections;
+                    const f = colls.find((c) => c.collection === collection)?.fields.find((x) => x.field === field);
+                    const ready = f?.index_ready === true;
+                    return { indexed: f?.indexed === true, index_ready: ready, reindex_required: f?.indexed === true && !ready };
+                }
+            },
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
              *  (design §5.1). Names an existing `string` field that holds the owner id. */
             setOwnerField: async (collection, ownerField) => {
@@ -1126,6 +1149,7 @@ export class Vxil {
                 let updated = 0;
                 let skipped = 0;
                 let pages = 0;
+                let indexCertify;
                 for (;;) {
                     let page = await this.cms.collections.reindex(collection, {
                         ...(opts?.field ? { field: opts.field } : {}),
@@ -1148,11 +1172,13 @@ export class Vxil {
                         opts?.onPage?.(page);
                     }
                     skipped += page.skipped ?? 0;
+                    if (page.index_certify)
+                        indexCertify = page.index_certify;
                     if (page.complete || !page.next_cursor)
                         break;
                     cursor = page.next_cursor;
                 }
-                return { scanned, updated, skipped, pages };
+                return { scanned, updated, skipped, pages, ...(indexCertify ? { index_certify: indexCertify } : {}) };
             },
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE

package/package.json

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