@vxil/sdk 0.1.0 → 0.2.0

package/README.md

@@ -12,15 +12,15 @@ import { Vxil } from '@vxil/sdk';
 const vx = new Vxil({ apiKey: process.env.VXIL_API_KEY! });
 
 await vx.users.upsert({ id: 'u_1', email: 'ada@example.com' });
-await vx.notifications.send({ to_user_id: 'u_1', template: 'welcome', data: { app_name: 'Demo' } });
+await vx.notifications.send({ user_id: 'u_1', template: 'welcome', data: { app_name: 'MyApp' } });
 const items = await vx.from('tasks').list({ status: 'open' });
 ```
 
 - Zero dependencies; works in Node ≥18, browsers, and edge runtimes.
 - Defaults to `https://api.vxil.com`; pass `baseUrl` to target another environment.
 - Every feature the tenant has enabled is available as a typed namespace; generate a
-  project-exact client with `npx vxil gen`.
+  project-exact client with `npx @vxil/cli gen`.
 
-Docs: [vxil.com](https://vxil.com) · Dashboard: [app.vxil.com](https://app.vxil.com) · Terms: [vxil.com/terms](https://vxil.com/terms)
+Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard) · Terms: [vxil.com/terms](https://vxil.com/terms)
 
 MIT © techmaker.io

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export interface VxilOptions {
     /** An end-user's vxil-`auth` **session token** (the ES256 JWT `auth` mints).
      *  When set, every request additionally carries it as the `X-Vxil-End-User`
      *  header — the edge verifies it and threads a **verified `end_user_id`** into
-     *  the inner JWT, putting the request in **end-user mode** (owner-scoped reads/
+     *  the request, putting it in **end-user mode** (owner-scoped reads/
      *  writes on owned collections; default-safe). This is the thin-client shape:
      *  a mobile/SPA holds a public/thin-client key + the signed-in user's session
      *  token and calls the edge directly, safely scoped to that user. Absent ⇒
@@ -84,6 +84,53 @@ export interface FeatureConfig {
     version: number;
     manifest: Record<string, unknown>;
 }
+/** An advisory plan from the planner (POST /v1/plan) — a proposal, not applied. */
+export interface VxilPlan {
+    app: {
+        name: string;
+        slug: string;
+        summary: string;
+        prompt: string;
+    };
+    /** features to enable, each with the capability that pulled it in. */
+    features: Array<{
+        feature: string;
+        why: string;
+    }>;
+    /** the raw features[] list for a quickstart body. */
+    enable: string[];
+    /** feature → materialized config manifest. */
+    config: Record<string, unknown>;
+    /** truly-unique server logic that needs a tenant function. */
+    functions: Array<{
+        why_unique: string;
+    }>;
+    /** cms collection drafts (AI tier; [] on the deterministic floor). */
+    collections: Array<{
+        name: string;
+        public?: boolean;
+        ownerField?: string;
+        fields: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+            unique?: boolean;
+            indexSlot?: string;
+            relationTo?: string;
+            onDelete?: string;
+        }>;
+    }>;
+    /** deny-clamped deploy-key scope union (informational). */
+    scopes: string[];
+    /** 1 = fully declarative; < 1 = some logic needs functions. */
+    thinness: number;
+    notes: string[];
+    /** a ready-to-review vxil.config.ts draft. */
+    config_draft: string;
+    rationale: string;
+    /** which brain produced the plan. */
+    source: 'ai' | 'deterministic';
+}
 export interface DeadLetter {
     delivery_id: string;
     template_id: string;
@@ -164,7 +211,7 @@ export interface PaymentsWebhookEvent {
     processed_at: string | null;
     reprocess_count: number;
     reprocessed_at: string | null;
-    /** detail-only: the verified provider payload (jsonb; '{}' for failed rows). */
+    /** detail-only: the verified provider payload (JSON; '{}' for failed rows). */
     payload?: unknown;
     /** detail-only: the raw body of a sig_failed/parse_failed delivery (≤64KB). */
     raw_body?: string | null;
@@ -315,7 +362,7 @@ export interface AiStreamHandle {
     connect_path?: string;
     resume_path: string;
 }
-/** Frames delivered over the ai:<generation_id> realtime channel and the
+/** Frames delivered over the ai-<generation_id> realtime channel and the
  *  ?since= replay buffer (the WS envelope is { event, data } — `event` is the
  *  frame type; replayed frames carry it as `type`). `title` arrives early when
  *  the stream was requested with title/title_template; only the terminal usage
@@ -670,6 +717,53 @@ export interface DmConfigState {
     version: number;
     configured: boolean;
 }
+/** The safe query subset the keyless cms public lane admits (roadmap §4.4): the
+ *  same bounded filter/sort/limit/cursor as the authored list, minus anything
+ *  owner- or lifecycle-scoped (the lane FORCES status='published'). `filter` is a
+ *  JSON object, serialized to the wire `filter=` param. */
+export interface CmsPublicQuery {
+    filter?: Record<string, unknown>;
+    sort?: string;
+    /** capped at 100 by the public lane regardless of the value sent. */
+    limit?: number;
+    cursor?: string;
+}
+/** One row on the keyless public lane: the item id + its authored data + the
+ *  public lifecycle timestamps. NO internal/system columns and NEVER the
+ *  owner_field (stripped server-side). */
+export interface CmsPublicRow {
+    item_id: string;
+    data: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    published_at: string | null;
+}
+/** Build the anonymous, KEYLESS public-delivery URL for a collection's PUBLISHED
+ *  items (roadmap §4.4) — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
+ *  the reader path a public blog/storefront/docs site hits with NO api key: the
+ *  edge mints a restricted read-only inner token bound to the URL tenant, forces
+ *  `status='published'`, and strips the collection's owner_field. PURE (no
+ *  network) — pass the result to `fetch`, an `<img>`/link, or `listCmsPublic`.
+ *  `baseUrl` defaults to `VXIL_BASE_URL` (Node) or the production edge, exactly
+ *  like the client constructor. */
+export declare function cmsPublicUrl(tenantId: string, collection: string, query?: CmsPublicQuery, opts?: {
+    baseUrl?: string;
+}): string;
+/** Fetch a page of a collection's PUBLISHED items over the KEYLESS public lane
+ *  (roadmap §4.4) — NO api key, no `Vxil` client, no auth of any kind. This is the
+ *  anonymous reader path (a blog/storefront/docs front-end). Returns the same
+ *  `{ items, next_cursor }` envelope the authed list does, but rows are stripped
+ *  to the public surface (`CmsPublicRow`) — drafts and the owner_field are never
+ *  present. A non-2xx throws `VxilError` carrying the envelope, as everywhere else.
+ *  The collection must be marked public (`collections.setPublic(collection, true)`
+ *  or `{ public: true }` on create) or the lane 404s (no not-public oracle). */
+export declare function listCmsPublic(tenantId: string, collection: string, query?: CmsPublicQuery, opts?: {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<{
+    items: CmsPublicRow[];
+    next_cursor: string | null;
+}>;
 /** The structural shape a `vxil gen`-generated `VxilSchema` satisfies. The base
  *  `Vxil` class is generic over it (`new Vxil<VxilSchema>(...)`), exactly the
  *  `createClient<Database>()` move — types are layered on; the runtime is
@@ -1111,6 +1205,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
         }>;
     };
+    /** The planner (config-architect): describe an app in plain English and get an
+     *  ADVISORY vxil plan — which features to enable, a materialized `config_draft`,
+     *  and which truly-unique logic needs a tenant function. Deterministic + pure;
+     *  it PROPOSES a plan, it never applies anything (review it, then push the
+     *  config). Needs `features:read`. (POST /v1/plan; docs/planner-feature-design.md) */
+    readonly planner: {
+        create: (description: string, name?: string) => Promise<VxilPlan>;
+    };
     readonly audit: {
         list: (q?: {
             since?: string;
@@ -1400,7 +1502,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         };
         /** End-user administration (server/function surface, auth:write). */
         users: {
-            /** GDPR PII erasure: anonymize the end-user's auth + tenant_users record
+            /** GDPR PII erasure: anonymize the end-user's auth + end-user identity record
              *  (email → tombstone, password/name/avatar cleared) and revoke every
              *  live session. Idempotent — a second call on an already-erased user is a
              *  no-op. Meant to be called from a "delete my account" server route or
@@ -1568,6 +1670,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  end-user principal (default-deny) in end-user mode; a no-op in
                  *  server-caller mode. Omit for shared/reference collections. */
                 owner_field?: string;
+                /** Public delivery (roadmap §4.4): when true, this collection's PUBLISHED
+                 *  items become KEYLESS-readable through the anonymous public lane —
+                 *  `GET {base}/v1/cms/public/:tenantId/:collection` with NO api key. Drafts
+                 *  and the owner_field are never exposed. Optional; defaults false. Use the
+                 *  top-level `cmsPublicUrl` / `listCmsPublic` helpers for the reader side. */
+                public?: boolean;
                 fields?: Array<{
                     field: string;
                     type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -1591,6 +1699,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 collection: string;
                 fields: number;
                 owner_field?: string;
+                public?: boolean;
             }>;
             list: () => Promise<Array<{
                 collection: string;
@@ -1602,6 +1711,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             /** 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>;
+            /** Toggle the collection's PUBLIC-delivery flag (roadmap §4.4). When `true`,
+             *  its PUBLISHED items become KEYLESS-readable via the anonymous public lane
+             *  (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
+             *  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>;
         };
         items: {
             /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
@@ -1621,11 +1736,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             get: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
-             * $contains $startsWith (LIKE-escaped; trigram-indexed on s*-slotted
-             * fields) $arrayContains/$anyOf (json/relation array containment via the
-             * JSONB GIN); range/sort needs slot-indexed fields. This is the
+             * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
+             * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
+             * range/sort needs slot-indexed fields. This is the
              * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
-             * admits, including unslotted range ops (served by unindexed JSONB
+             * admits, including unslotted range ops (served by unindexed
              * scans, bounded only by the statement timeout) that the generated
              * per-field `Filterable` unions on `vx.from(...).query` exclude.
              */
@@ -2270,7 +2385,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             settings?: Record<string, unknown>;
             role?: string | null;
         }>;
-        /** Update a workspace's name / `settings` jsonb. */
+        /** Update a workspace's name / `settings` JSON. */
         update: (orgId: string, patch: {
             name?: string;
             settings?: Record<string, unknown>;
@@ -2521,7 +2636,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     };
     /**
      * Managed hybrid search (the `vector-search` feature): store documents → chunk →
-     * embed → index, then retrieve top-k via hybrid (BM25 ∪ vector, RRF-fused),
+     * embed → index, then retrieve top-k via hybrid (keyword ∪ vector, RRF-fused),
      * vector, or keyword. The embedder is config: 'mock' (deterministic default),
      * 'byov' (you supply vectors), or a BYO-key provider (openai/cohere).
      */

package/dist/index.js

@@ -43,6 +43,57 @@ function resolveBase(explicit) {
     const envBase = g.process?.env?.VXIL_BASE_URL;
     return (explicit ?? envBase ?? DEFAULT_BASE).replace(/\/$/, '');
 }
+/** Build the anonymous, KEYLESS public-delivery URL for a collection's PUBLISHED
+ *  items (roadmap §4.4) — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
+ *  the reader path a public blog/storefront/docs site hits with NO api key: the
+ *  edge mints a restricted read-only inner token bound to the URL tenant, forces
+ *  `status='published'`, and strips the collection's owner_field. PURE (no
+ *  network) — pass the result to `fetch`, an `<img>`/link, or `listCmsPublic`.
+ *  `baseUrl` defaults to `VXIL_BASE_URL` (Node) or the production edge, exactly
+ *  like the client constructor. */
+export function cmsPublicUrl(tenantId, collection, query, opts) {
+    const base = resolveBase(opts?.baseUrl);
+    const path = `/v1/cms/public/${encodeURIComponent(tenantId)}/${encodeURIComponent(collection)}`;
+    const qs = new URLSearchParams();
+    if (query?.filter)
+        qs.set('filter', JSON.stringify(query.filter));
+    if (query?.sort)
+        qs.set('sort', query.sort);
+    if (query?.limit !== undefined)
+        qs.set('limit', String(query.limit));
+    if (query?.cursor)
+        qs.set('cursor', query.cursor);
+    const s = qs.toString();
+    return `${base}${path}${s ? `?${s}` : ''}`;
+}
+/** Fetch a page of a collection's PUBLISHED items over the KEYLESS public lane
+ *  (roadmap §4.4) — NO api key, no `Vxil` client, no auth of any kind. This is the
+ *  anonymous reader path (a blog/storefront/docs front-end). Returns the same
+ *  `{ items, next_cursor }` envelope the authed list does, but rows are stripped
+ *  to the public surface (`CmsPublicRow`) — drafts and the owner_field are never
+ *  present. A non-2xx throws `VxilError` carrying the envelope, as everywhere else.
+ *  The collection must be marked public (`collections.setPublic(collection, true)`
+ *  or `{ public: true }` on create) or the lane 404s (no not-public oracle). */
+export async function listCmsPublic(tenantId, collection, query, opts) {
+    const url = cmsPublicUrl(tenantId, collection, query, opts);
+    const fetchImpl = opts?.fetch ?? fetch;
+    const res = await fetchImpl(url, { method: 'GET' });
+    const text = await res.text();
+    let parsed = {};
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new VxilError(res.status, `http_${res.status}`, text.slice(0, 200));
+        }
+    }
+    if (!res.ok || parsed.error) {
+        const e = parsed.error ?? { code: `http_${res.status}`, message: text.slice(0, 200) };
+        throw new VxilError(res.status, e.code, e.message, e.hint, e.fixUrl, parsed.meta?.request_id);
+    }
+    return parsed.data ?? { items: [], next_cursor: null };
+}
 export class Vxil {
     base;
     key;
@@ -302,6 +353,17 @@ export class Vxil {
          * stable flat-array shorthand. */
         summary: async () => (await this.call('GET', '/v1/features')).data,
     };
+    /** The planner (config-architect): describe an app in plain English and get an
+     *  ADVISORY vxil plan — which features to enable, a materialized `config_draft`,
+     *  and which truly-unique logic needs a tenant function. Deterministic + pure;
+     *  it PROPOSES a plan, it never applies anything (review it, then push the
+     *  config). Needs `features:read`. (POST /v1/plan; docs/planner-feature-design.md) */
+    planner = {
+        create: async (description, name) => (await this.call('POST', '/v1/plan', {
+            description,
+            ...(name ? { name } : {}),
+        })).data,
+    };
     audit = {
         list: async (q) => {
             const qs = new URLSearchParams();
@@ -481,7 +543,7 @@ export class Vxil {
         },
         /** End-user administration (server/function surface, auth:write). */
         users: {
-            /** GDPR PII erasure: anonymize the end-user's auth + tenant_users record
+            /** GDPR PII erasure: anonymize the end-user's auth + end-user identity record
              *  (email → tombstone, password/name/avatar cleared) and revoke every
              *  live session. Idempotent — a second call on an already-erased user is a
              *  no-op. Meant to be called from a "delete my account" server route or
@@ -574,6 +636,14 @@ export class Vxil {
             setOwnerField: async (collection, ownerField) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField });
             },
+            /** Toggle the collection's PUBLIC-delivery flag (roadmap §4.4). When `true`,
+             *  its PUBLISHED items become KEYLESS-readable via the anonymous public lane
+             *  (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
+             *  the owner_field are never exposed. `false` closes the lane (and purges the
+             *  edge cache). Read the public side with `cmsPublicUrl` / `listCmsPublic`. */
+            setPublic: async (collection, isPublic) => {
+                await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
+            },
         },
         items: {
             /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
@@ -582,11 +652,11 @@ export class Vxil {
             get: async (collection, itemId) => (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`)).data,
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
-             * $contains $startsWith (LIKE-escaped; trigram-indexed on s*-slotted
-             * fields) $arrayContains/$anyOf (json/relation array containment via the
-             * JSONB GIN); range/sort needs slot-indexed fields. This is the
+             * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
+             * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
+             * range/sort needs slot-indexed fields. This is the
              * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
-             * admits, including unslotted range ops (served by unindexed JSONB
+             * admits, including unslotted range ops (served by unindexed
              * scans, bounded only by the statement timeout) that the generated
              * per-field `Filterable` unions on `vx.from(...).query` exclude.
              */
@@ -937,7 +1007,7 @@ export class Vxil {
         sessionClaims: async (userId) => (await this.call('GET', `/v1/orgs/session-claims?user_id=${encodeURIComponent(userId)}`)).data,
         /** Read one workspace (incl. `settings`). */
         get: async (orgId) => (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}`)).data,
-        /** Update a workspace's name / `settings` jsonb. */
+        /** Update a workspace's name / `settings` JSON. */
         update: async (orgId, patch) => (await this.call('PATCH', `/v1/orgs/${encodeURIComponent(orgId)}`, patch)).data,
         members: {
             add: async (orgId, userId, role) => {
@@ -1060,7 +1130,7 @@ export class Vxil {
     };
     /**
      * Managed hybrid search (the `vector-search` feature): store documents → chunk →
-     * embed → index, then retrieve top-k via hybrid (BM25 ∪ vector, RRF-fused),
+     * embed → index, then retrieve top-k via hybrid (keyword ∪ vector, RRF-fused),
      * vector, or keyword. The embedder is config: 'mock' (deterministic default),
      * 'byov' (you supply vectors), or a BYO-key provider (openai/cohere).
      */

package/package.json

@@ -1,19 +1,11 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",
   "license": "MIT",
   "homepage": "https://vxil.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vxilhq/vxil.git",
-    "directory": "packages/sdk"
-  },
-  "bugs": {
-    "url": "https://github.com/vxilhq/vxil/issues"
-  },
   "keywords": [
     "backend",
     "baas",