@content-island/vscode-api-client 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -5,12 +5,22 @@ declare type AllowedFields<M extends Model, Type extends 'sort' | 'filter'> = Pa
 }, 'fields.id' | 'fields.language'>>;
 
 declare interface ApiClient {
+    /**
+     * Resolves the project. Routed by the client-level mode only (no per-query override): served from
+     * the snapshot's `project` block in `'snapshot'` mode, from the API in `'api'` mode.
+     */
     getProject: () => Promise<Project>;
     getContentList: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListQueryParams<M>) => Promise<M[]>;
     getContent: <M extends Model = Model & Record<string, any>>(queryParam: ContentQueryParams<M>) => Promise<M>;
     getRawContentList: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListQueryParams<M>) => Promise<Content[]>;
     getRawContent: <M extends Model = Model & Record<string, any>>(queryParam: ContentQueryParams<M>) => Promise<Content>;
     getContentListSize: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListSizeQueryParams<M>) => Promise<number>;
+    /**
+     * Resolves the snapshot's `meta` block, lazily loading the snapshot regardless of mode (from
+     * `snapshotPath`, or `DEFAULT_SNAPSHOT_PATH` when omitted). Rejects with an `ApiClientError` from
+     * the loader on a missing/unreadable/invalid file.
+     */
+    getSnapshotInfo: () => Promise<SnapshotMeta>;
     /**
      * Updates (or upserts, when selected by `fieldName`+`language`) a field value on an existing content.
      *
@@ -32,6 +42,18 @@ declare interface ApiClient {
      * the live snapshot from the current draft.
      */
     publishContent: (contentId: string) => Promise<boolean>;
+    /** Creates an Entity model. Rejects with `ApiClientError` on non-2xx. */
+    createModel: (params: CreateEntityParams) => Promise<SaveModelResponse>;
+    /** Full-upsert of an Entity model: the supplied `fieldList` replaces the stored one. */
+    updateModel: (modelId: string, params: UpdateEntityParams) => Promise<SaveModelResponse>;
+    /** Deletes a model. Rejects with `ApiClientError` (e.g. 409 when referenced). */
+    deleteModel: (modelId: string) => Promise<boolean>;
+    /** Creates an Enum model. Rejects with `ApiClientError` on non-2xx. */
+    createEnum: (params: CreateEnumParams) => Promise<SaveModelResponse>;
+    /** Full-upsert of an Enum model: the supplied `values` replace the stored ones. */
+    updateEnum: (enumId: string, params: UpdateEnumParams) => Promise<SaveModelResponse>;
+    /** Deletes an enum. Rejects with `ApiClientError` (e.g. 409 when referenced). */
+    deleteEnum: (enumId: string) => Promise<boolean>;
 }
 
 declare interface BaseModel {
@@ -46,6 +68,8 @@ export declare type ClientFilter<Type = string | boolean | number> = Type | {
     nin?: Type[];
 };
 
+declare type ClientMode = 'api' | 'snapshot';
+
 export declare interface Content {
     id: string;
     name: string;
@@ -87,6 +111,19 @@ declare interface CreateContentResponse {
     id: string;
 }
 
+declare interface CreateEntityParams {
+    name: string;
+    fieldList: FieldSpec[];
+}
+
+declare interface CreateEnumParams {
+    name: string;
+    values: Array<{
+        id?: string;
+        value: string;
+    }>;
+}
+
 declare interface Entity extends BaseModel {
     type: 'entity';
     fieldList?: Field_2[];
@@ -131,6 +168,21 @@ declare type FieldSelector = {
     language: string;
 };
 
+/**
+ * Structured field spec. `id` is optional: present = existing field to preserve
+ * on update, absent = the server creates it. `relatedModelId` is a 24-char model
+ * id used only for `relation`/`enum` types. `order` never appears (server derives
+ * it by list position).
+ */
+declare interface FieldSpec {
+    id?: string;
+    name: string;
+    type: FieldTypeSpec;
+    relatedModelId?: string;
+    isArray?: boolean;
+    validations?: Validation[];
+}
+
 export declare type FieldType =
 | 'short-text'
 | 'long-text'
@@ -142,6 +194,19 @@ export declare type FieldType =
 | 'color'
 | RelatedModelType;
 
+/**
+ * Agent-facing field type discriminator (the value an agent supplies for a field's
+ * `type` when creating/editing a model). The B2B server translates `relation`/`enum`
+ * + `relatedModelId` into the stored `` `${modelId}|${Name}` `` type string; the
+ * agent never supplies a composite type string.
+ *
+ * Derived from common's stored `FieldType` (single source of truth): the 8 primitive
+ * tokens (the stored type minus the composite `${id}|${Name}` form) plus the two
+ * agent-facing discriminators. Distinct from the read-side `FieldType` (common), which
+ * is the composite the server returns on content/project responses.
+ */
+declare type FieldTypeSpec = Exclude<FieldType, `${string}|${string}`> | 'relation' | 'enum';
+
 declare type FilterableFields<M extends Model = Model> = {
     id?: ClientFilter<string>;
     lastUpdate?: ClientFilter<string>;
@@ -367,6 +432,19 @@ declare interface Options {
     secureProtocol?: boolean;
     apiVersion?: string;
     metadata?: string;
+    /**
+     * Client-level mode. `'api'` (default) performs network requests against the B2B API;
+     * `'snapshot'` serves reads from a snapshot file loaded from `snapshotPath`.
+     */
+    mode?: ClientMode;
+    /**
+     * Path to a content snapshot file (produced by `content-island export`). Optional and cwd-relative;
+     * defaults to `DEFAULT_SNAPSHOT_PATH` — the same path the CLI writes by default, so export followed
+     * by `createClient({ mode: 'snapshot' })` resolves the same file with zero config. Independent of
+     * `mode`: an `'api'` client may still set it to expose `getSnapshotInfo()`. A missing/unreadable/
+     * invalid file at the resolved path rejects with an `ApiClientError` from the loader.
+     */
+    snapshotPath?: string;
 }
 
 declare type Pagination = {
@@ -384,10 +462,43 @@ export declare interface Project {
 declare type QueryParams<M extends Model = Model & Record<string, any>> = FilterableFields<M> & {
     sort?: SortableFields<M>;
     pagination?: Pagination;
+    /**
+     * Per-query mode override (effective mode = per-query `mode` ?? client-level `mode` ?? `'api'`).
+     * Client-only key — never serialized into the query string.
+     */
+    mode?: ClientMode;
+    /**
+     * Called exactly once with the related-content resolution metadata; when omitted, behavior and
+     * return shapes are unchanged. Client-only key — never serialized into the query string.
+     */
+    onRelatedContentMeta?: (meta: RelatedContentMeta) => void;
+};
+
+/**
+ * Related-content resolution metadata for a read: how deep the BFS resolved (`resolvedDepth`) and
+ * whether a depth/budget cap left the graph `partial`. Identical values in both modes for the same
+ * data and query (header-sourced in api mode, engine-sourced in snapshot mode).
+ */
+declare type RelatedContentMeta = {
+    resolvedDepth: number;
+    partial: boolean;
 };
 
 declare type RelatedModelType = `${string}|${string}`;
 
+/** Committed-operation success response for create/update model/enum. */
+declare interface SaveModelResponse {
+    id: string;
+}
+
+declare interface SnapshotMeta {
+    schemaVersion: number;
+    /** ISO-8601 timestamp of when the snapshot was generated on the server. */
+    exportedAt: string;
+    projectId: string;
+    view: 'published' | 'preview';
+}
+
 declare type SortableFields<M extends Model> = {
     contentType?: SortOrder;
     lastUpdate?: SortOrder;
@@ -397,6 +508,10 @@ declare type SortOrder = 'asc' | 'desc';
 
 declare type Status = 'draft' | 'published' | 'changed';
 
+declare type UpdateEntityParams = CreateEntityParams;
+
+declare type UpdateEnumParams = CreateEnumParams;
+
 declare interface UploadMediaParams {
     file: Blob | File;
     fileName?: string;
@@ -404,7 +519,7 @@ declare interface UploadMediaParams {
 
 declare type Validation = { name: string; customArgs?: any };
 
-export declare interface VSCodeApiClient extends ApiClient {
+export declare interface VSCodeApiClient extends Omit<ApiClient, 'createModel' | 'updateModel' | 'deleteModel' | 'createEnum' | 'updateEnum' | 'deleteEnum'> {
     setVSCodeExtensionContext: (context: vscode.ExtensionContext) => void;
     authorize: (authorizationCode: string, metadata: string) => Promise<void>;
     authorizeByProjectId: (projectId: string) => Promise<void>;

package/dist/index.js

@@ -2,52 +2,52 @@ import { isApiClientError as I, createClient as A } from "@content-island/api-cl
 import { mapContentToModel as z } from "@content-island/api-client";
 import * as c from "vscode";
 import _ from "node:crypto";
-import P from "node:util";
-let g;
-const S = () => {
-  if (!g)
+import S from "node:util";
+let C;
+const P = () => {
+  if (!C)
     throw new Error("Extension context has not been set.");
-  return g;
-}, L = (t) => {
-  g = t;
+  return C;
+}, f = (t) => {
+  C = t;
 };
 let l = {
-  getContext: S,
-  setContext: L
+  getContext: P,
+  setContext: f
 };
 const d = {
   IS_PRODUCTION: !0,
   DEFAULT_API_CLIENT_DOMAIN: "api.contentisland.net",
   DEFAULT_API_CLIENT_VERSION: "1.0",
   DEFAULT_LOGIN_DOMAIN: "app.contentisland.net"
-}, C = "content-island-vscode", u = {
-  SALT: `${C}.salt`,
-  ACCESS_TOKEN_BY_PROJECT_ID: (t) => `${C}.access-token.${t}`,
-  METADATA_BY_PROJECT_ID: (t) => `${C}.metadata.${t}`
-}, E = {
+}, w = "content-island-vscode", u = {
+  SALT: `${w}.salt`,
+  ACCESS_TOKEN_BY_PROJECT_ID: (t) => `${w}.access-token.${t}`,
+  METADATA_BY_PROJECT_ID: (t) => `${w}.metadata.${t}`
+}, h = {
   get: async (t) => await l.getContext().secrets.get(u.METADATA_BY_PROJECT_ID(t)),
   set: async (t, o) => {
     await l.getContext().secrets.store(u.METADATA_BY_PROJECT_ID(t), o);
   }
-}, h = {
+}, E = {
   get: async (t) => await l.getContext().secrets.get(u.ACCESS_TOKEN_BY_PROJECT_ID(t)),
   set: async (t, o) => {
     await l.getContext().secrets.store(u.ACCESS_TOKEN_BY_PROJECT_ID(t), o);
   }
-}, f = (t) => {
-  const s = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.domain ? t.domain : d.DEFAULT_API_CLIENT_DOMAIN, n = t.apiVersion ? t.apiVersion : d.DEFAULT_API_CLIENT_VERSION;
-  return `${s}://${e}/api/${n}`;
+}, L = (t) => {
+  const a = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.domain ? t.domain : d.DEFAULT_API_CLIENT_DOMAIN, n = t.apiVersion ? t.apiVersion : d.DEFAULT_API_CLIENT_VERSION;
+  return `${a}://${e}/api/${n}`;
 }, p = (t) => {
-  const s = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.loginDomain ? t.loginDomain : d.DEFAULT_LOGIN_DOMAIN;
-  return `${s}://${e}/#/?redirect=vscode`;
-}, y = 16, O = (t = y) => _.randomBytes(t).toString("hex"), x = 64, D = "sha512", m = 1e5, N = async (t, o, s = x) => (await P.promisify(_.pbkdf2)(t, o, m, s, D)).toString("hex"), k = async () => {
+  const a = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.loginDomain ? t.loginDomain : d.DEFAULT_LOGIN_DOMAIN;
+  return `${a}://${e}/#/?redirect=vscode`;
+}, y = 16, O = (t = y) => _.randomBytes(t).toString("hex"), x = 64, D = "sha512", m = 1e5, N = async (t, o, a = x) => (await S.promisify(_.pbkdf2)(t, o, m, a, D)).toString("hex"), k = async () => {
   const t = l.getContext();
   let o = await t.secrets.get(u.SALT);
   return o || (o = O(32), await t.secrets.store(u.SALT, o)), o;
 }, M = 32, R = async (t) => {
   const o = await k();
   return await N(t, o, M);
-}, w = async (t) => {
+}, g = async (t) => {
   const o = "Open Login Page";
   if (await c.window.showInformationMessage(
     "You need to log in to Content Island to continue. Do you want to open the login page?",
@@ -56,23 +56,23 @@ const d = {
     return;
   const e = c.Uri.parse(p(t));
   await c.env.openExternal(e);
-}, r = (t, o) => async (...s) => {
+}, s = (t, o) => async (...a) => {
   try {
-    return await t(...s);
+    return await t(...a);
   } catch (e) {
     if (I(e)) {
       if (e.status === 401)
-        throw await w(o), new Error("Unauthorized: Please log in to continue.");
+        throw await g(o), new Error("Unauthorized: Please log in to continue.");
       e.status === 403 && c.window.showErrorMessage("Access forbidden: You do not have permission to perform this action.");
     }
     throw e;
   }
-}, U = async (t, o, s) => {
-  const e = f(t);
+}, U = async (t, o, a) => {
+  const e = L(t);
   let n;
-  const a = {
+  const r = {
     authorizationCode: o,
-    metadata: s
+    metadata: a
   };
   try {
     n = await fetch(`${e}/security/vscode/token`, {
@@ -80,7 +80,7 @@ const d = {
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify(a)
+      body: JSON.stringify(r)
     });
   } catch {
     c.window.showErrorMessage(
@@ -89,7 +89,7 @@ const d = {
     return;
   }
   if (!n.ok) {
-    n.status === 401 ? await w(t) : n.status === 403 && c.window.showErrorMessage(
+    n.status === 401 ? await g(t) : n.status === 403 && c.window.showErrorMessage(
       "You do not have permission to access this resource. Please check your access rights in Content Island."
     ), c.window.showErrorMessage(
       "Failed to obtain access token. Please complete the authorization in Content Island."
@@ -98,16 +98,16 @@ const d = {
   }
   try {
     const i = await n.json();
-    return (!i?.accessToken || typeof i.accessToken != "string") && (c.window.showErrorMessage("Invalid response from the authorization server."), await w(t)), i.accessToken;
+    return (!i?.accessToken || typeof i.accessToken != "string") && (c.window.showErrorMessage("Invalid response from the authorization server."), await g(t)), i.accessToken;
   } catch {
     c.window.showErrorMessage("Error processing response from the authorization server.");
   }
 }, T = (t) => {
-  const o = `PREVIEW_${t.accessToken}`, s = A({ ...t, accessToken: o });
+  const o = `PREVIEW_${t.accessToken}`, a = A({ ...t, accessToken: o });
   return {
-    ...s,
+    ...a,
     getProject: async () => {
-      const e = await s.getProject();
+      const e = await a.getProject();
       return {
         ...e,
         id: await R(e.id)
@@ -116,42 +116,43 @@ const d = {
   };
 }, B = (t = {}) => {
   let o = T({ ...t, accessToken: "" });
-  const s = (e, n) => {
+  const a = (e, n) => {
     o = T({ ...t, accessToken: e, metadata: n });
   };
   return {
     authorize: async (e, n) => {
-      const a = await U(t, e, n);
-      if (a) {
-        s(a, n);
+      const r = await U(t, e, n);
+      if (r) {
+        a(r, n);
         const i = await o.getProject();
-        await h.set(i.id, a), await E.set(i.id, n);
+        await E.set(i.id, r), await h.set(i.id, n);
       }
     },
     authorizeByProjectId: async (e) => {
-      const n = await h.get(e), a = await E.get(e);
-      if (!n || !a) {
-        await w(t);
+      const n = await E.get(e), r = await h.get(e);
+      if (!n || !r) {
+        await g(t);
         return;
       }
-      s(n, a);
+      a(n, r);
     },
     setVSCodeExtensionContext: (e) => {
       l.setContext(e);
     },
-    getProject: (...e) => r(() => o.getProject(...e), t)(),
-    getContentList: (...e) => r(() => o.getContentList(...e), t)(),
-    getContent: (...e) => r(() => o.getContent(...e), t)(),
-    getRawContentList: (...e) => r(() => o.getRawContentList(...e), t)(),
-    getRawContent: (...e) => r(() => o.getRawContent(...e), t)(),
-    getContentListSize: (...e) => r(() => o.getContentListSize(...e), t)(),
-    updateContentFieldValue: (e, n, a) => r(
-      () => o.updateContentFieldValue(e, n, a),
+    getProject: (...e) => s(() => o.getProject(...e), t)(),
+    getContentList: (...e) => s(() => o.getContentList(...e), t)(),
+    getContent: (...e) => s(() => o.getContent(...e), t)(),
+    getRawContentList: (...e) => s(() => o.getRawContentList(...e), t)(),
+    getRawContent: (...e) => s(() => o.getRawContent(...e), t)(),
+    getContentListSize: (...e) => s(() => o.getContentListSize(...e), t)(),
+    getSnapshotInfo: (...e) => s(() => o.getSnapshotInfo(...e), t)(),
+    updateContentFieldValue: (e, n, r) => s(
+      () => o.updateContentFieldValue(e, n, r),
       t
     )(),
-    uploadMedia: (...e) => r(() => o.uploadMedia(...e), t)(),
-    createContent: (...e) => r(() => o.createContent(...e), t)(),
-    publishContent: (...e) => r(() => o.publishContent(...e), t)()
+    uploadMedia: (...e) => s(() => o.uploadMedia(...e), t)(),
+    createContent: (...e) => s(() => o.createContent(...e), t)(),
+    publishContent: (...e) => s(() => o.publishContent(...e), t)()
   };
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@content-island/vscode-api-client",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Content Island - VSCode Extension API Client",
   "private": false,
   "sideEffects": false,
@@ -32,7 +32,7 @@
     "test:watch": "vitest -c ./config/test/config.ts"
   },
   "dependencies": {
-    "@content-island/api-client": "0.21.0"
+    "@content-island/api-client": "0.23.0"
   },
   "devDependencies": {
     "@content-island/common-backend": "*",