@syntaxcircus/cmsify-client 0.0.0-bootstrap.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Syntax Circus LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# `@syntaxcircus/cmsify-client`
+
+The first-party TypeScript client provides a typed, server/edge delivery facade for Cmsify content, templates, and media. It targets Node 20+ and modern edge runtimes; do not import it into browser bundles or expose its API token to client-side code.
+
+For management, authentication, or any endpoint beyond the curated delivery facade, use the exported generated fetch client instead.
+
+## Install and build locally
+
+```powershell
+Set-Location sdk/typescript
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run test:consumer
+```
+
+`test:consumer` packs the SDK, installs it into an empty temporary consumer, and typechecks that consumer and the checked-in Next.js, Astro, and SvelteKit server examples through only public exports. CI runs it on Node 20 and 22.
+
+## Configure a server-side delivery client
+
+```ts
+import { CmsifyClient } from "@syntaxcircus/cmsify-client";
+
+const cms = new CmsifyClient({
+  baseUrl: process.env.CMSIFY_API_URL!,
+  apiToken: process.env.CMSIFY_API_TOKEN!,
+  workspaceId: process.env.CMSIFY_WORKSPACE_ID!, // GUID only; slugs are rejected
+  timeoutMs: 5_000,
+});
+
+const posts = await cms.content.list({
+  status: "Published",
+  tags: "featured",
+  sortBy: "publishedAt",
+  pageSize: 10,
+});
+
+const post = await cms.content.bySlug("my-first-post");
+```
+
+List operations return `{ items, totalCount, page, pageSize, totalPages }`, including `content.translations`. Consume every page with `content.listAll`:
+
+```ts
+for await (const post of cms.content.listAll({ status: "Published" })) {
+  console.log(post.slug);
+}
+```
+
+Keep `CMSIFY_API_TOKEN` in a server-only secret store. The checked-in Next.js App Router, Astro, and SvelteKit examples use server/private environment mechanisms. API tokens are opaque bearer credentials; applications must not parse or reconstruct them.
+
+## Generated raw client
+
+The complete generated OpenAPI surface remains available without weakening the delivery facade:
+
+```ts
+import { createCmsifyFetchClient, type paths } from "@syntaxcircus/cmsify-client";
+
+const raw = createCmsifyFetchClient(process.env.CMSIFY_API_URL!);
+const response = await raw.GET("/api/v1/workspaces/{workspaceId}/content", {
+  params: { path: { workspaceId: process.env.CMSIFY_WORKSPACE_ID! } },
+});
+```
+
+`generated`, `paths`, and `components` are also exported for generated schema access. Generated files under `src/generated` are not handwritten API surface and must be regenerated only through the OpenAPI workflow.
+
+## Errors, retries, cancellation, and concurrency
+
+Failures are `CmsifyApiError` instances carrying RFC 7807 fields (`type`, `title`, `status`, `detail`, `errors`, `extensions`, and `traceId`) plus the server correlation ID. `CmsifyTimeoutError` identifies an expired SDK timeout budget.
+
+By default the client retries `429`, transient `5xx`, and transport faults up to three attempts for idempotent methods only. `Retry-After` supports both delta-seconds and HTTP-date values. A non-idempotent request is retried only when `RequestOptions.idempotencyKey` is supplied. Pass `retry: false`, `timeoutMs`, or a caller `signal` in `RequestOptions` to control one request; timeout budgets include retries and a caller abort is never retried.
+
+ETags from read responses are tracked and used as `If-Match` on later mutations of the same URL. An explicit `ifMatch` overrides the tracked ETag. Successful empty and `204 No Content` responses return `undefined`.
+
+## OpenAPI generation
+
+Generated files are under `src/generated` and should not be edited by hand. After an API contract change:
+
+```powershell
+Set-Location ../..
+dotnet restore Cmsify.slnx --locked-mode
+node scripts/openapi.mjs update
+Set-Location sdk/typescript
+npm run generate:check
+npm run typecheck
+npm test
+npm run build
+npm run test:consumer
+```
+
+`update` is the only command allowed to modify the checked-in OpenAPI snapshot or generated TypeScript files. `generate:check` is non-mutating: it exports the live document and generates into a temporary directory before checking live-to-snapshot and generated-to-tracked drift. Both commands build `Cmsify.Api` with `--no-restore`, so complete the applicable public or approved ignored-feed locked solution restore from the repository root first.

package/dist/index.cjs

@@ -0,0 +1,333 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CmsifyApiError: () => CmsifyApiError,
+  CmsifyClient: () => CmsifyClient,
+  CmsifyTimeoutError: () => CmsifyTimeoutError,
+  ETagStore: () => ETagStore,
+  TEXT_FORMAT_HINTS: () => TEXT_FORMAT_HINTS,
+  createCmsifyFetchClient: () => createCmsifyFetchClient,
+  generated: () => schema_exports,
+  getFormatHint: () => getFormatHint,
+  isProseHint: () => isProseHint,
+  listAll: () => listAll,
+  toMimeType: () => toMimeType
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/etag.ts
+var ETagStore = class {
+  values = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.values.get(key);
+  }
+  set(key, etag) {
+    if (etag) {
+      this.values.set(key, etag);
+    }
+  }
+};
+
+// src/errors.ts
+var CmsifyApiError = class extends Error {
+  problem;
+  status;
+  traceId;
+  correlationId;
+  constructor(problem, correlationId) {
+    super(problem.detail ?? problem.title ?? `Cmsify API request failed with ${problem.status ?? "unknown status"}`);
+    this.name = "CmsifyApiError";
+    this.problem = problem;
+    this.status = problem.status ?? 0;
+    this.traceId = typeof problem.traceId === "string" ? problem.traceId : void 0;
+    this.correlationId = correlationId;
+  }
+};
+var CmsifyTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Cmsify API request exceeded its ${timeoutMs}ms timeout budget.`);
+    this.name = "CmsifyTimeoutError";
+  }
+};
+var isProblemDetails = (value) => typeof value === "object" && value !== null && ("status" in value || "title" in value || "type" in value);
+
+// src/pagination.ts
+async function* listAll(loader) {
+  for (let page = 1; ; page += 1) {
+    const result = await loader(page);
+    for (const item of result.items) {
+      yield item;
+    }
+    if (page >= result.totalPages || result.items.length === 0) {
+      return;
+    }
+  }
+}
+
+// src/client.ts
+var CmsifyClient = class {
+  content = {
+    list: (options = {}) => this.request(this.workspacePath("/content", contentQuery(options, true))),
+    listAll: (options = {}) => listAll((page) => this.content.list({ ...options, page })),
+    get: (id, options = {}) => this.request(this.workspacePath(`/content/${encodeURIComponent(id)}`, detailQuery(options))),
+    bySlug: (slug, options = {}) => this.request(this.workspacePath(`/content/by-slug/${encodeURIComponent(slug)}`, detailQuery(options, false))),
+    translations: (id, options = {}) => this.request(this.workspacePath(`/content/${encodeURIComponent(id)}/translations`, pageQuery(options)))
+  };
+  templates = {
+    list: (options = {}) => this.request(this.workspacePath("/templates", pageQuery(options))),
+    get: (id) => this.request(this.workspacePath(`/templates/${encodeURIComponent(id)}`))
+  };
+  media = {
+    list: (options = {}) => this.request(this.workspacePath("/media", pageQuery(options))),
+    get: (id) => this.request(this.workspacePath(`/media/${encodeURIComponent(id)}`)),
+    download: (id) => this.request(this.workspacePath(`/media/${encodeURIComponent(id)}/file`), {}, {}, "blob")
+  };
+  baseUrl;
+  baseOrigin;
+  workspaceId;
+  token;
+  fetchImpl;
+  retryByDefault;
+  timeoutMs;
+  now;
+  delay;
+  etags = new ETagStore();
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.baseOrigin = new URL(this.baseUrl).origin;
+    this.workspaceId = options.workspaceId;
+    this.token = options.apiToken;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.retryByDefault = options.retry !== false;
+    this.timeoutMs = options.timeoutMs;
+    this.now = options.now ?? Date.now;
+    this.delay = options.delay ?? delay;
+  }
+  async request(path, init = {}, options = {}, responseType = "json") {
+    const url = this.requestUrl(path);
+    const headers = new Headers(init.headers);
+    headers.set("Accept", responseType === "blob" ? "*/*" : "application/json");
+    headers.set("X-Correlation-Id", createCorrelationId());
+    if (this.token) headers.set("Authorization", `Bearer ${this.token}`);
+    if (init.body && !headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+    if (options.idempotencyKey) headers.set("Idempotency-Key", options.idempotencyKey);
+    const method = (init.method ?? "GET").toUpperCase();
+    const trackedEtag = options.ifMatch ?? this.etags.get(url);
+    if (trackedEtag && isMutation(method)) headers.set("If-Match", trackedEtag);
+    const retry = (options.retry ?? this.retryByDefault) && (isIdempotent(method) || Boolean(options.idempotencyKey)) && isReplayableBody(init.body);
+    const response = await this.fetchWithRetry(url, { ...init, headers }, retry, options.signal, options.timeoutMs ?? this.timeoutMs);
+    this.etags.set(url, response.headers.get("ETag"));
+    if (!response.ok) {
+      const correlationId = response.headers.get("X-Correlation-Id") ?? headers.get("X-Correlation-Id") ?? void 0;
+      const body = await this.safeReadJson(response);
+      const problem = isProblemDetails(body) ? { ...body, status: response.status } : { status: response.status, title: response.statusText };
+      throw new CmsifyApiError(problem, correlationId);
+    }
+    if (hasEmptySuccessBody(response)) return void 0;
+    if (responseType === "blob") return await response.blob();
+    return await this.safeReadJson(response);
+  }
+  workspacePath(path, query) {
+    if (!isGuid(this.workspaceId)) throw new Error("workspaceId must be a GUID.");
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) if (value !== void 0) search.set(key, String(value));
+    const suffix = search.size > 0 ? `?${search}` : "";
+    return `/api/v1/workspaces/${encodeURIComponent(this.workspaceId)}${path}${suffix}`;
+  }
+  requestUrl(path) {
+    const url = new URL(path, `${this.baseUrl}/`);
+    if (url.origin !== this.baseOrigin) throw new Error("CmsifyClient requests must target the configured Cmsify origin.");
+    return url.toString();
+  }
+  async fetchWithRetry(url, init, retry, callerSignal, timeoutMs) {
+    const deadline = timeoutMs === void 0 ? void 0 : this.now() + Math.max(0, timeoutMs);
+    for (let attempt = 1; ; attempt += 1) {
+      const controller = new AbortController();
+      const timeout = timeoutMs === void 0 ? void 0 : Math.max(0, (deadline ?? this.now()) - this.now());
+      const cleanup = connectAbortSignals(controller, callerSignal, timeout, timeoutMs);
+      try {
+        const response = await this.fetchImpl(url, { ...init, signal: controller.signal });
+        if (!retry || attempt >= 3 || !isRetryableResponse(response)) return response;
+        await this.delay(retryDelay(response.headers.get("Retry-After"), attempt, this.now), controller.signal);
+      } catch (error) {
+        if (controller.signal.aborted) throw controller.signal.reason ?? error;
+        if (!retry || attempt >= 3 || !isTransportFault(error)) throw error;
+        await this.delay(100 * 2 ** (attempt - 1), controller.signal);
+      } finally {
+        cleanup();
+      }
+    }
+  }
+  async safeReadJson(response) {
+    const text = await response.text();
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { status: response.status, title: response.statusText };
+    }
+  }
+};
+var contentQuery = (options, resolve) => ({
+  Q: options.q,
+  TemplateVersionId: options.templateVersionId,
+  TemplateId: options.templateId,
+  Status: options.status,
+  LocaleCode: options.localeCode,
+  TranslationGroupId: options.translationGroupId,
+  Slug: options.slug,
+  Tags: options.tags,
+  CreatedAfter: asIso(options.createdAfter),
+  CreatedBefore: asIso(options.createdBefore),
+  PublishedAfter: asIso(options.publishedAfter),
+  PublishedBefore: asIso(options.publishedBefore),
+  Resolve: resolve,
+  AsOf: asIso(options.asOf),
+  SortBy: options.sortBy,
+  SortDesc: options.sortDesc,
+  page: options.page,
+  pageSize: options.pageSize
+});
+var detailQuery = (options, resolve = true) => options.asOf === void 0 ? {} : { ...resolve ? { resolve: true } : {}, asOf: asIso(options.asOf) };
+var pageQuery = (options) => ({ page: options.page, pageSize: options.pageSize });
+var asIso = (value) => value instanceof Date ? value.toISOString() : value;
+var isGuid = (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+var isIdempotent = (method) => ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"].includes(method);
+var isMutation = (method) => !["GET", "HEAD", "OPTIONS"].includes(method);
+var isRetryableResponse = (response) => response.status === 429 || response.status >= 500;
+var isTransportFault = (error) => error instanceof TypeError || error instanceof Error && error.name === "NetworkError";
+var isReplayableBody = (body) => !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+var hasEmptySuccessBody = (response) => response.status === 204 || response.headers.get("Content-Length") === "0";
+var retryDelay = (header, attempt, now) => retryAfterDelay(header, now) ?? 100 * 2 ** (attempt - 1);
+var retryAfterDelay = (header, now) => {
+  if (header === null) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(header);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now());
+};
+var connectAbortSignals = (controller, callerSignal, timeout, timeoutBudget) => {
+  const abortForCaller = () => controller.abort(callerSignal?.reason);
+  if (callerSignal?.aborted) abortForCaller();
+  else callerSignal?.addEventListener("abort", abortForCaller, { once: true });
+  const timer = timeout === void 0 ? void 0 : setTimeout(() => controller.abort(new CmsifyTimeoutError(timeoutBudget ?? timeout)), timeout);
+  return () => {
+    callerSignal?.removeEventListener("abort", abortForCaller);
+    if (timer !== void 0) clearTimeout(timer);
+  };
+};
+var delay = (milliseconds, signal) => new Promise((resolve, reject) => {
+  if (signal.aborted) {
+    reject(signal.reason);
+    return;
+  }
+  const timer = setTimeout(resolve, milliseconds);
+  signal.addEventListener("abort", () => {
+    clearTimeout(timer);
+    reject(signal.reason);
+  }, { once: true });
+});
+var createCorrelationId = () => globalThis.crypto?.randomUUID?.() ?? `cmsify-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+// src/formatting.ts
+var TEXT_FORMAT_HINTS = [
+  "plaintext",
+  "html",
+  "markdown",
+  "json",
+  "xml",
+  "yaml",
+  "csv",
+  "toml",
+  "sql",
+  "code",
+  "url",
+  "email",
+  "regex"
+];
+var MIME_BY_HINT = {
+  plaintext: "text/plain",
+  html: "text/html",
+  markdown: "text/markdown",
+  json: "application/json",
+  xml: "application/xml",
+  yaml: "application/yaml",
+  csv: "text/csv",
+  toml: "application/toml",
+  sql: "application/sql",
+  code: "text/plain",
+  url: "text/uri-list",
+  email: "text/plain",
+  regex: "text/plain"
+};
+function toMimeType(hint) {
+  if (hint && hint in MIME_BY_HINT) {
+    return MIME_BY_HINT[hint];
+  }
+  return "text/plain";
+}
+function getFormatHint(fieldConfig) {
+  if (!fieldConfig || typeof fieldConfig !== "object") {
+    return "plaintext";
+  }
+  const raw = fieldConfig.formatHint;
+  if (typeof raw !== "string") {
+    return "plaintext";
+  }
+  const normalized = raw.toLowerCase();
+  return TEXT_FORMAT_HINTS.includes(normalized) ? normalized : "plaintext";
+}
+function isProseHint(hint) {
+  return hint === "plaintext" || hint === "markdown" || hint === "html";
+}
+
+// src/generated/schema.ts
+var schema_exports = {};
+
+// src/generated/client.ts
+var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
+var createCmsifyFetchClient = (baseUrl, fetchImpl) => fetchImpl ? (0, import_openapi_fetch.default)({ baseUrl, fetch: fetchImpl }) : (0, import_openapi_fetch.default)({ baseUrl });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CmsifyApiError,
+  CmsifyClient,
+  CmsifyTimeoutError,
+  ETagStore,
+  TEXT_FORMAT_HINTS,
+  createCmsifyFetchClient,
+  generated,
+  getFormatHint,
+  isProseHint,
+  listAll,
+  toMimeType
+});
+//# sourceMappingURL=index.cjs.map