cmskite 0.1.0

package/dist/index.cjs

@@ -0,0 +1,348 @@
+'use strict';
+
+// src/errors.ts
+var CMSKiteError = class extends Error {
+  /** HTTP status, or 0 when no response arrived at all. */
+  status;
+  /** A stable machine-readable reason. Safe to branch on; see the constants. */
+  code;
+  /** Whatever the API attached. Field-level validation problems live here. */
+  details;
+  /** Quote this when asking us about a request. */
+  requestId;
+  constructor(status, code, message, details = {}, requestId = null) {
+    super(message);
+    this.name = "CMSKiteError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.requestId = requestId;
+  }
+  /** Nothing you send differently will change the answer. */
+  get isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+  /** Worth trying again. The client already retried once. */
+  get isRetryable() {
+    return this.status === 0 || this.status === 429 || this.status >= 500;
+  }
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** The key is missing, wrong, or has been revoked. */
+  get isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+};
+var ErrorCode = {
+  NETWORK: "NETWORK",
+  TIMEOUT: "TIMEOUT",
+  BAD_RESPONSE: "BAD_RESPONSE",
+  UNAUTHENTICATED: "UNAUTHENTICATED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  RATE_LIMITED: "RATE_LIMITED",
+  INVALID_REQUEST: "INVALID_REQUEST"
+};
+
+// src/transport.ts
+var DEFAULT_BASE_URL = "https://api.cmskite.com";
+var VERSION = "0.1.0";
+async function request(config, method, path, init = {}) {
+  const url = buildUrl(config.baseUrl, path, init.query);
+  const timeoutMs = init.options?.timeoutMs ?? config.timeoutMs;
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return await once(config, method, url, timeoutMs, init);
+    } catch (error) {
+      const failure = error instanceof CMSKiteError ? error : toError(error);
+      if (init.options?.signal?.aborted) throw failure;
+      if (!failure.isRetryable || attempt === 1) throw failure;
+      lastError = failure;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+  throw lastError ?? new CMSKiteError(0, ErrorCode.NETWORK, "Request failed.");
+}
+async function once(config, method, url, timeoutMs, init) {
+  const timeout = new AbortController();
+  const timer = setTimeout(() => timeout.abort(), timeoutMs);
+  const signal = init.options?.signal ? AbortSignal.any([init.options.signal, timeout.signal]) : timeout.signal;
+  let response;
+  let text;
+  try {
+    response = await config.fetch(url, {
+      method,
+      signal,
+      headers: {
+        authorization: `Bearer ${config.apiKey}`,
+        accept: "application/json",
+        "x-cmskite-sdk": VERSION,
+        ...init.body === void 0 ? {} : { "content-type": "application/json" },
+        ...config.headers
+      },
+      ...init.body === void 0 ? {} : { body: JSON.stringify(init.body) }
+    });
+    text = await response.text();
+  } catch (error) {
+    throw toError(error, timeout.signal.aborted, timeoutMs);
+  } finally {
+    clearTimeout(timer);
+  }
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    throw new CMSKiteError(
+      response.status,
+      ErrorCode.BAD_RESPONSE,
+      "CMSKite returned something this client could not read.",
+      {},
+      response.headers.get("x-request-id")
+    );
+  }
+  if (!response.ok || payload.success === false) {
+    throw new CMSKiteError(
+      response.status,
+      payload.error?.code ?? codeForStatus(response.status),
+      payload.error?.message ?? `CMSKite answered ${response.status}.`,
+      payload.error?.details ?? {},
+      payload.requestId ?? response.headers.get("x-request-id")
+    );
+  }
+  const result = { data: payload.data };
+  if (payload.pagination) result.pagination = payload.pagination;
+  return result;
+}
+function toError(error, timedOut = false, timeoutMs = 0) {
+  if (error instanceof CMSKiteError) return error;
+  if (timedOut) {
+    return new CMSKiteError(0, ErrorCode.TIMEOUT, `CMSKite did not answer within ${timeoutMs}ms.`);
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    return new CMSKiteError(0, ErrorCode.NETWORK, "The request was cancelled.");
+  }
+  return new CMSKiteError(0, ErrorCode.NETWORK, "Could not reach CMSKite. Check the connection.");
+}
+function codeForStatus(status) {
+  if (status === 401) return ErrorCode.UNAUTHENTICATED;
+  if (status === 403) return ErrorCode.FORBIDDEN;
+  if (status === 404) return ErrorCode.NOT_FOUND;
+  if (status === 429) return ErrorCode.RATE_LIMITED;
+  if (status >= 400 && status < 500) return ErrorCode.INVALID_REQUEST;
+  return "INTERNAL_ERROR";
+}
+function buildUrl(baseUrl, path, query = {}) {
+  const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+// src/client.ts
+var CMSKite = class {
+  posts;
+  categories;
+  tags;
+  authors;
+  /** @internal Not part of the public surface; the shape here may change. */
+  config;
+  constructor(options) {
+    if (!options?.apiKey) {
+      throw new CMSKiteError(
+        0,
+        ErrorCode.INVALID_REQUEST,
+        "createCMSKite needs an apiKey. Create one under Project \u2192 API keys."
+      );
+    }
+    this.config = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      timeoutMs: options.timeoutMs ?? 1e4,
+      headers: options.headers ?? {},
+      // Bound, because an unbound `fetch` throws "Illegal invocation" in a
+      // browser -- a failure that only appears in the environment that matters
+      // most and reads as nothing to do with us.
+      fetch: (options.fetch ?? globalThis.fetch).bind(globalThis)
+    };
+    this.posts = new Posts(this.config);
+    this.categories = new Categories(this.config);
+    this.tags = new Tags(this.config);
+    this.authors = new Authors(this.config);
+  }
+};
+function page(result) {
+  return {
+    items: result.data ?? [],
+    pagination: result.pagination ?? { hasNext: false, nextCursor: null, limit: 0 }
+  };
+}
+var Posts = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /** A page of posts. Published only, newest first, unless you say otherwise. */
+  async list(query = {}, options) {
+    const result = await request(this.config, "GET", "v1/blog/posts", {
+      query: { ...query, withTotal: query.withTotal ? "true" : void 0 },
+      ...options ? { options } : {}
+    });
+    return page(result);
+  }
+  /** One post by its id. The body is always included. */
+  async get(id, options) {
+    const result = await request(this.config, "GET", `v1/blog/posts/${encodeURIComponent(id)}`, {
+      ...options ? { options } : {}
+    });
+    return result.data;
+  }
+  /**
+   * One post by its address.
+   *
+   * This is what a page at `/blog/[slug]` wants. An old slug still resolves,
+   * and the answer carries `slugRedirectedFrom` so the page can issue a 301
+   * rather than quietly serving two addresses for one post.
+   */
+  async getBySlug(slug, options) {
+    const result = await request(
+      this.config,
+      "GET",
+      `v1/blog/posts/slug/${encodeURIComponent(slug)}`,
+      { ...options ? { options } : {} }
+    );
+    return result.data;
+  }
+  /**
+   * The same as `getBySlug`, but a missing post is `null` rather than a throw.
+   *
+   * For a page that renders its own not-found state, which is most of them.
+   */
+  async findBySlug(slug, options) {
+    try {
+      return await this.getBySlug(slug, options);
+    } catch (error) {
+      if (error instanceof CMSKiteError && error.isNotFound) return null;
+      throw error;
+    }
+  }
+  /** Posts like this one, chosen by shared tags and category. */
+  async related(id, query = {}, options) {
+    const result = await request(
+      this.config,
+      "GET",
+      `v1/blog/posts/${encodeURIComponent(id)}/related`,
+      { query, ...options ? { options } : {} }
+    );
+    return page(result);
+  }
+  /** Full-text search across titles and bodies. */
+  async search(q, query = {}, options) {
+    const result = await request(this.config, "GET", "v1/blog/search", {
+      query: { q, ...query },
+      ...options ? { options } : {}
+    });
+    return page(result);
+  }
+  /**
+   * Every post, a page at a time, without writing the cursor loop.
+   *
+   * An async iterator rather than an array, so a site with four thousand posts
+   * does not hold four thousand posts in memory to generate a sitemap.
+   *
+   *     for await (const post of cms.posts.all()) { … }
+   */
+  async *all(query = {}, options) {
+    let cursor;
+    do {
+      const result = await this.list(
+        { ...query, ...cursor ? { cursor } : {} },
+        options
+      );
+      for (const item of result.items) yield item;
+      cursor = result.pagination.nextCursor ?? void 0;
+    } while (cursor);
+  }
+};
+var Categories = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async list(query = {}, options) {
+    return page(
+      await request(this.config, "GET", "v1/blog/categories", {
+        query,
+        ...options ? { options } : {}
+      })
+    );
+  }
+  async get(id, options) {
+    const result = await request(
+      this.config,
+      "GET",
+      `v1/blog/categories/${encodeURIComponent(id)}`,
+      { ...options ? { options } : {} }
+    );
+    return result.data;
+  }
+};
+var Tags = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async list(query = {}, options) {
+    return page(
+      await request(this.config, "GET", "v1/blog/tags", {
+        query,
+        ...options ? { options } : {}
+      })
+    );
+  }
+  async get(id, options) {
+    const result = await request(
+      this.config,
+      "GET",
+      `v1/blog/tags/${encodeURIComponent(id)}`,
+      { ...options ? { options } : {} }
+    );
+    return result.data;
+  }
+};
+var Authors = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async list(query = {}, options) {
+    return page(
+      await request(this.config, "GET", "v1/blog/authors", {
+        query,
+        ...options ? { options } : {}
+      })
+    );
+  }
+  async get(id, options) {
+    const result = await request(
+      this.config,
+      "GET",
+      `v1/blog/authors/${encodeURIComponent(id)}`,
+      { ...options ? { options } : {} }
+    );
+    return result.data;
+  }
+};
+function createCMSKite(options) {
+  return new CMSKite(options);
+}
+
+exports.CMSKite = CMSKite;
+exports.CMSKiteError = CMSKiteError;
+exports.ErrorCode = ErrorCode;
+exports.createCMSKite = createCMSKite;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/transport.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * One error type, so a caller writes one catch.\n *\n * Everything that can go wrong on the way to an answer arrives as a\n * `CMSKiteError`: a refusal from the API, a dropped connection, a timeout, a\n * response that was not JSON. Without that, a `catch` has to tell a `TypeError`\n * from a `SyntaxError` from whatever the API said, and the ones that forget\n * show somebody \"Failed to fetch\" -- a sentence about our code rather than\n * about their connection.\n */\nexport class CMSKiteError extends Error {\n  /** HTTP status, or 0 when no response arrived at all. */\n  readonly status: number\n  /** A stable machine-readable reason. Safe to branch on; see the constants. */\n  readonly code: string\n  /** Whatever the API attached. Field-level validation problems live here. */\n  readonly details: Record<string, unknown>\n  /** Quote this when asking us about a request. */\n  readonly requestId: string | null\n\n  constructor(\n    status: number,\n    code: string,\n    message: string,\n    details: Record<string, unknown> = {},\n    requestId: string | null = null,\n  ) {\n    super(message)\n    this.name = 'CMSKiteError'\n    this.status = status\n    this.code = code\n    this.details = details\n    this.requestId = requestId\n  }\n\n  /** Nothing you send differently will change the answer. */\n  get isClientError(): boolean {\n    return this.status >= 400 && this.status < 500\n  }\n\n  /** Worth trying again. The client already retried once. */\n  get isRetryable(): boolean {\n    return this.status === 0 || this.status === 429 || this.status >= 500\n  }\n\n  get isNotFound(): boolean {\n    return this.status === 404\n  }\n\n  /** The key is missing, wrong, or has been revoked. */\n  get isAuthError(): boolean {\n    return this.status === 401 || this.status === 403\n  }\n}\n\n/**\n * The codes worth branching on, as values rather than as strings scattered\n * through a codebase.\n */\nexport const ErrorCode = {\n  NETWORK: 'NETWORK',\n  TIMEOUT: 'TIMEOUT',\n  BAD_RESPONSE: 'BAD_RESPONSE',\n  UNAUTHENTICATED: 'UNAUTHENTICATED',\n  FORBIDDEN: 'FORBIDDEN',\n  NOT_FOUND: 'NOT_FOUND',\n  RATE_LIMITED: 'RATE_LIMITED',\n  INVALID_REQUEST: 'INVALID_REQUEST',\n} as const\n\nexport type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode]\n","import { CMSKiteError, ErrorCode } from './errors.js'\nimport type { Page, RequestOptions } from './types.js'\n\nexport const DEFAULT_BASE_URL = 'https://api.cmskite.com'\n/**\n * What a caller may pass as a query.\n *\n * An interface with named optional fields -- which every query type here is --\n * does not satisfy `Record<string, unknown>`, because TypeScript will not give\n * one an implicit index signature. Widening to `object` and reading entries off\n * it is the honest way to accept both, and the values are stringified anyway.\n */\ntype QueryInput = Record<string, unknown> | object\n\n/** Sent so we can tell an SDK request from a hand-rolled one in support. */\nconst VERSION = '0.1.0'\n\nexport interface TransportConfig {\n  apiKey: string\n  baseUrl: string\n  timeoutMs: number\n  /** Extra headers on every request. For a proxy or a trace id. */\n  headers: Record<string, string>\n  fetch: typeof globalThis.fetch\n}\n\ninterface Envelope<T> {\n  success?: boolean\n  data?: T\n  pagination?: Page<T>['pagination']\n  error?: { code?: string; message?: string; details?: Record<string, unknown> }\n  requestId?: string\n}\n\n/**\n * One request, and everything that can go wrong with it turned into one type.\n *\n * Retries exactly once, and only what a retry can fix: a dropped connection, a\n * timeout, a 429, a 5xx. A 404 is a settled answer and asking again only delays\n * showing somebody the truth. A 401 will not become a 200 by being repeated.\n */\nexport async function request<T>(\n  config: TransportConfig,\n  method: string,\n  path: string,\n  init: { query?: QueryInput; body?: unknown; options?: RequestOptions } = {},\n): Promise<{ data: T; pagination?: Page<T>['pagination'] }> {\n  const url = buildUrl(config.baseUrl, path, init.query)\n  const timeoutMs = init.options?.timeoutMs ?? config.timeoutMs\n\n  let lastError: CMSKiteError | null = null\n  for (let attempt = 0; attempt < 2; attempt++) {\n    try {\n      return await once<T>(config, method, url, timeoutMs, init)\n    } catch (error) {\n      const failure = error instanceof CMSKiteError ? error : toError(error)\n      // A caller who aborted wants the abort, not a retry and not our wrapper.\n      if (init.options?.signal?.aborted) throw failure\n      if (!failure.isRetryable || attempt === 1) throw failure\n      lastError = failure\n      // One short pause. Anything longer is a decision the caller should make.\n      await new Promise((resolve) => setTimeout(resolve, 250))\n    }\n  }\n\n  throw lastError ?? new CMSKiteError(0, ErrorCode.NETWORK, 'Request failed.')\n}\n\nasync function once<T>(\n  config: TransportConfig,\n  method: string,\n  url: string,\n  timeoutMs: number,\n  init: { body?: unknown; options?: RequestOptions },\n): Promise<{ data: T; pagination?: Page<T>['pagination'] }> {\n  /**\n   * The caller's signal and our timeout, combined.\n   *\n   * `AbortSignal.any` is the correct tool and exists everywhere this package\n   * supports; the timeout controller is still created so that a timeout can be\n   * told apart from a caller's abort in the catch below.\n   */\n  const timeout = new AbortController()\n  const timer = setTimeout(() => timeout.abort(), timeoutMs)\n  const signal = init.options?.signal\n    ? AbortSignal.any([init.options.signal, timeout.signal])\n    : timeout.signal\n\n  let response: Response\n  let text: string\n  try {\n    response = await config.fetch(url, {\n      method,\n      signal,\n      headers: {\n        authorization: `Bearer ${config.apiKey}`,\n        accept: 'application/json',\n        'x-cmskite-sdk': VERSION,\n        ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),\n        ...config.headers,\n      },\n      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),\n    })\n    text = await response.text()\n  } catch (error) {\n    throw toError(error, timeout.signal.aborted, timeoutMs)\n  } finally {\n    clearTimeout(timer)\n  }\n\n  let payload: Envelope<T>\n  try {\n    payload = text ? (JSON.parse(text) as Envelope<T>) : {}\n  } catch {\n    throw new CMSKiteError(\n      response.status,\n      ErrorCode.BAD_RESPONSE,\n      'CMSKite returned something this client could not read.',\n      {},\n      response.headers.get('x-request-id'),\n    )\n  }\n\n  if (!response.ok || payload.success === false) {\n    throw new CMSKiteError(\n      response.status,\n      payload.error?.code ?? codeForStatus(response.status),\n      payload.error?.message ?? `CMSKite answered ${response.status}.`,\n      payload.error?.details ?? {},\n      payload.requestId ?? response.headers.get('x-request-id'),\n    )\n  }\n\n  const result: { data: T; pagination?: Page<T>['pagination'] } = { data: payload.data as T }\n  if (payload.pagination) result.pagination = payload.pagination\n  return result\n}\n\nfunction toError(error: unknown, timedOut = false, timeoutMs = 0): CMSKiteError {\n  if (error instanceof CMSKiteError) return error\n  if (timedOut) {\n    return new CMSKiteError(0, ErrorCode.TIMEOUT, `CMSKite did not answer within ${timeoutMs}ms.`)\n  }\n  if (error instanceof Error && error.name === 'AbortError') {\n    return new CMSKiteError(0, ErrorCode.NETWORK, 'The request was cancelled.')\n  }\n  return new CMSKiteError(0, ErrorCode.NETWORK, 'Could not reach CMSKite. Check the connection.')\n}\n\nfunction codeForStatus(status: number): string {\n  if (status === 401) return ErrorCode.UNAUTHENTICATED\n  if (status === 403) return ErrorCode.FORBIDDEN\n  if (status === 404) return ErrorCode.NOT_FOUND\n  if (status === 429) return ErrorCode.RATE_LIMITED\n  if (status >= 400 && status < 500) return ErrorCode.INVALID_REQUEST\n  return 'INTERNAL_ERROR'\n}\n\n/**\n * Query building, in one place.\n *\n * `undefined`, `null` and the empty string are dropped rather than sent, so a\n * caller can pass an optional filter straight through without writing the same\n * three-line guard at every call site.\n */\nexport function buildUrl(baseUrl: string, path: string, query: QueryInput = {}): string {\n  const url = new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`)\n  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {\n    if (value === undefined || value === null || value === '') continue\n    url.searchParams.set(key, String(value))\n  }\n  return url.toString()\n}\n","import { CMSKiteError, ErrorCode } from './errors.js'\nimport { DEFAULT_BASE_URL, request, type TransportConfig } from './transport.js'\nimport type {\n  Author,\n  Category,\n  ListPostsQuery,\n  ListQuery,\n  Page,\n  Post,\n  RequestOptions,\n  Tag,\n} from './types.js'\n\nexport interface CMSKiteOptions {\n  /**\n   * A CMSKite API key. Read-only, and scoped to one project.\n   *\n   * Safe in a browser bundle: the only scope a key can hold is `blog:read`, it\n   * cannot write or delete anything, and a project can restrict which origins\n   * may use it. See the security section of the README.\n   */\n  apiKey: string\n  /** Only for a self-hosted deployment or a local API. */\n  baseUrl?: string\n  /** How long to wait for an answer. Default 10 seconds. */\n  timeoutMs?: number\n  /** Extra headers on every request, for a proxy or a trace id. */\n  headers?: Record<string, string>\n  /** Supply your own, for a test double or a fetch with retries built in. */\n  fetch?: typeof globalThis.fetch\n}\n\n/**\n * The CMSKite client.\n *\n * Created once and reused. It holds no connection and no mutable state beyond\n * its configuration, so it is safe to build at module scope and share.\n *\n *     const cms = createCMSKite({ apiKey: process.env.CMSKITE_API_KEY! })\n *     const { items } = await cms.posts.list({ limit: 10 })\n *\n * Every method takes an optional `{ signal }`, so a request can be cancelled\n * when a component unmounts or a newer search supersedes an older one.\n */\nexport class CMSKite {\n  readonly posts: Posts\n  readonly categories: Categories\n  readonly tags: Tags\n  readonly authors: Authors\n  /** @internal Not part of the public surface; the shape here may change. */\n  private readonly config: TransportConfig\n\n  constructor(options: CMSKiteOptions) {\n    if (!options?.apiKey) {\n      throw new CMSKiteError(\n        0,\n        ErrorCode.INVALID_REQUEST,\n        'createCMSKite needs an apiKey. Create one under Project → API keys.',\n      )\n    }\n\n    this.config = {\n      apiKey: options.apiKey,\n      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,\n      timeoutMs: options.timeoutMs ?? 10_000,\n      headers: options.headers ?? {},\n      // Bound, because an unbound `fetch` throws \"Illegal invocation\" in a\n      // browser -- a failure that only appears in the environment that matters\n      // most and reads as nothing to do with us.\n      fetch: (options.fetch ?? globalThis.fetch).bind(globalThis),\n    }\n\n    this.posts = new Posts(this.config)\n    this.categories = new Categories(this.config)\n    this.tags = new Tags(this.config)\n    this.authors = new Authors(this.config)\n  }\n}\n\n/**\n * The shape a list endpoint answers with, normalised.\n *\n * The wire says `{ data, pagination }`. This says `{ items, pagination }`,\n * because a caller writing `posts.items.map(...)` should not have to know that\n * our envelope calls it `data`.\n */\nfunction page<T>(result: { data: T[]; pagination?: Page<T>['pagination'] }): Page<T> {\n  return {\n    items: result.data ?? [],\n    pagination: result.pagination ?? { hasNext: false, nextCursor: null, limit: 0 },\n  }\n}\n\nclass Posts {\n  constructor(private readonly config: TransportConfig) {}\n\n  /** A page of posts. Published only, newest first, unless you say otherwise. */\n  async list(query: ListPostsQuery = {}, options?: RequestOptions): Promise<Page<Post>> {\n    const result = await request<Post[]>(this.config, 'GET', 'v1/blog/posts', {\n      query: { ...query, withTotal: query.withTotal ? 'true' : undefined },\n      ...(options ? { options } : {}),\n    })\n    return page(result)\n  }\n\n  /** One post by its id. The body is always included. */\n  async get(id: string, options?: RequestOptions): Promise<Post> {\n    const result = await request<Post>(this.config, 'GET', `v1/blog/posts/${encodeURIComponent(id)}`, {\n      ...(options ? { options } : {}),\n    })\n    return result.data\n  }\n\n  /**\n   * One post by its address.\n   *\n   * This is what a page at `/blog/[slug]` wants. An old slug still resolves,\n   * and the answer carries `slugRedirectedFrom` so the page can issue a 301\n   * rather than quietly serving two addresses for one post.\n   */\n  async getBySlug(slug: string, options?: RequestOptions): Promise<Post> {\n    const result = await request<Post>(\n      this.config,\n      'GET',\n      `v1/blog/posts/slug/${encodeURIComponent(slug)}`,\n      { ...(options ? { options } : {}) },\n    )\n    return result.data\n  }\n\n  /**\n   * The same as `getBySlug`, but a missing post is `null` rather than a throw.\n   *\n   * For a page that renders its own not-found state, which is most of them.\n   */\n  async findBySlug(slug: string, options?: RequestOptions): Promise<Post | null> {\n    try {\n      return await this.getBySlug(slug, options)\n    } catch (error) {\n      if (error instanceof CMSKiteError && error.isNotFound) return null\n      throw error\n    }\n  }\n\n  /** Posts like this one, chosen by shared tags and category. */\n  async related(id: string, query: ListQuery = {}, options?: RequestOptions): Promise<Page<Post>> {\n    const result = await request<Post[]>(\n      this.config,\n      'GET',\n      `v1/blog/posts/${encodeURIComponent(id)}/related`,\n      { query, ...(options ? { options } : {}) },\n    )\n    return page(result)\n  }\n\n  /** Full-text search across titles and bodies. */\n  async search(\n    q: string,\n    query: ListQuery = {},\n    options?: RequestOptions,\n  ): Promise<Page<Post>> {\n    const result = await request<Post[]>(this.config, 'GET', 'v1/blog/search', {\n      query: { q, ...query },\n      ...(options ? { options } : {}),\n    })\n    return page(result)\n  }\n\n  /**\n   * Every post, a page at a time, without writing the cursor loop.\n   *\n   * An async iterator rather than an array, so a site with four thousand posts\n   * does not hold four thousand posts in memory to generate a sitemap.\n   *\n   *     for await (const post of cms.posts.all()) { … }\n   */\n  async *all(\n    query: Omit<ListPostsQuery, 'cursor'> = {},\n    options?: RequestOptions,\n  ): AsyncGenerator<Post, void, undefined> {\n    let cursor: string | undefined\n    do {\n      const result: Page<Post> = await this.list(\n        { ...query, ...(cursor ? { cursor } : {}) },\n        options,\n      )\n      for (const item of result.items) yield item\n      cursor = result.pagination.nextCursor ?? undefined\n    } while (cursor)\n  }\n}\n\nclass Categories {\n  constructor(private readonly config: TransportConfig) {}\n\n  async list(query: ListQuery = {}, options?: RequestOptions): Promise<Page<Category>> {\n    return page(\n      await request<Category[]>(this.config, 'GET', 'v1/blog/categories', {\n        query,\n        ...(options ? { options } : {}),\n      }),\n    )\n  }\n\n  async get(id: string, options?: RequestOptions): Promise<Category> {\n    const result = await request<Category>(\n      this.config,\n      'GET',\n      `v1/blog/categories/${encodeURIComponent(id)}`,\n      { ...(options ? { options } : {}) },\n    )\n    return result.data\n  }\n}\n\nclass Tags {\n  constructor(private readonly config: TransportConfig) {}\n\n  async list(query: ListQuery = {}, options?: RequestOptions): Promise<Page<Tag>> {\n    return page(\n      await request<Tag[]>(this.config, 'GET', 'v1/blog/tags', {\n        query,\n        ...(options ? { options } : {}),\n      }),\n    )\n  }\n\n  async get(id: string, options?: RequestOptions): Promise<Tag> {\n    const result = await request<Tag>(\n      this.config,\n      'GET',\n      `v1/blog/tags/${encodeURIComponent(id)}`,\n      { ...(options ? { options } : {}) },\n    )\n    return result.data\n  }\n}\n\nclass Authors {\n  constructor(private readonly config: TransportConfig) {}\n\n  async list(query: ListQuery = {}, options?: RequestOptions): Promise<Page<Author>> {\n    return page(\n      await request<Author[]>(this.config, 'GET', 'v1/blog/authors', {\n        query,\n        ...(options ? { options } : {}),\n      }),\n    )\n  }\n\n  async get(id: string, options?: RequestOptions): Promise<Author> {\n    const result = await request<Author>(\n      this.config,\n      'GET',\n      `v1/blog/authors/${encodeURIComponent(id)}`,\n      { ...(options ? { options } : {}) },\n    )\n    return result.data\n  }\n}\n\n/** Creates a client. The function, rather than `new`, is the documented way in. */\nexport function createCMSKite(options: CMSKiteOptions): CMSKite {\n  return new CMSKite(options)\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,278 @@
+/**
+ * The shapes CMSKite answers with.
+ *
+ * These mirror the API's own response schemas rather than its database, and
+ * that distinction is the SDK's main promise to a customer: a column added,
+ * renamed or moved behind the scenes is not their problem. What is documented
+ * here is what will keep working.
+ *
+ * Every interface is open to new optional fields. A minor release may add one;
+ * none will remove one or change the meaning of one.
+ */
+type BodyFormat = 'markdown' | 'html' | 'text';
+type PostStatus = 'draft' | 'published' | 'scheduled';
+interface Author {
+    id: string;
+    name: string;
+    slug: string;
+    bio: string | null;
+    avatarUrl: string | null;
+}
+interface Category {
+    id: string;
+    name: string;
+    slug: string;
+    /** `engineering/databases` — the full path, so two "Guides" can be told apart. */
+    path: string;
+    depth: number;
+}
+interface Tag {
+    id: string;
+    name: string;
+    slug: string;
+}
+interface Media {
+    id: string;
+    url: string;
+    alt: string | null;
+    width: number | null;
+    height: number | null;
+}
+interface Seo {
+    title?: string | null;
+    description?: string | null;
+    canonicalUrl?: string | null;
+    ogImageUrl?: string | null;
+    noindex?: boolean;
+}
+interface Post {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    /** Empty when `bodyOmitted` is true, which is how a list stays small. */
+    body: string;
+    /**
+     * Whether the body was left out of this response.
+     *
+     * List endpoints omit it: twenty posts with full bodies is a payload nobody
+     * asked for. Fetching one post always includes it.
+     */
+    bodyOmitted: boolean;
+    bodyFormat: BodyFormat;
+    status: PostStatus;
+    author: Author | null;
+    category: Category | null;
+    tags: Tag[];
+    featuredMedia: Media | null;
+    publishedAt: string | null;
+    scheduledAt: string | null;
+    seo: Seo;
+    /** Addresses this post used to live at. Useful for issuing redirects. */
+    previousSlugs: string[];
+    /** Set when the post was reached by one of its old slugs. */
+    slugRedirectedFrom: string | null;
+    wordCount: number;
+    readingMinutes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Pagination {
+    hasNext: boolean;
+    /** Opaque. Pass it back as `cursor`; never parse it. */
+    nextCursor: string | null;
+    limit: number;
+    /** Only present when the request asked for it. Counting is not free. */
+    total?: number;
+}
+/**
+ * A page of results.
+ *
+ * `items` rather than `data`, because `data` is what the wire calls it and the
+ * wire is an implementation detail. Iterating a page directly is the common
+ * case, so the array is the first thing you reach.
+ */
+interface Page<T> {
+    items: T[];
+    pagination: Pagination;
+}
+type PostSort = 'publishedAt' | '-publishedAt' | 'updatedAt' | '-updatedAt' | 'createdAt' | '-createdAt' | 'title' | '-title';
+interface ListPostsQuery {
+    /** Default 20, maximum 100. */
+    limit?: number;
+    /** From a previous page's `pagination.nextCursor`. */
+    cursor?: string;
+    status?: PostStatus;
+    /** Category slug or id. */
+    category?: string;
+    /** Tag slug or id. */
+    tag?: string;
+    author?: string;
+    sort?: PostSort;
+    /** Free text across title and body. */
+    search?: string;
+    publishedAfter?: string;
+    publishedBefore?: string;
+    /** Ask for `pagination.total`. Costs a count; off by default. */
+    withTotal?: boolean;
+}
+interface ListQuery {
+    limit?: number;
+    cursor?: string;
+}
+interface RequestOptions {
+    /** Cancels the request. Every method takes one. */
+    signal?: AbortSignal;
+    /** Overrides the client's default for this call only. */
+    timeoutMs?: number;
+}
+
+interface TransportConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    /** Extra headers on every request. For a proxy or a trace id. */
+    headers: Record<string, string>;
+    fetch: typeof globalThis.fetch;
+}
+
+interface CMSKiteOptions {
+    /**
+     * A CMSKite API key. Read-only, and scoped to one project.
+     *
+     * Safe in a browser bundle: the only scope a key can hold is `blog:read`, it
+     * cannot write or delete anything, and a project can restrict which origins
+     * may use it. See the security section of the README.
+     */
+    apiKey: string;
+    /** Only for a self-hosted deployment or a local API. */
+    baseUrl?: string;
+    /** How long to wait for an answer. Default 10 seconds. */
+    timeoutMs?: number;
+    /** Extra headers on every request, for a proxy or a trace id. */
+    headers?: Record<string, string>;
+    /** Supply your own, for a test double or a fetch with retries built in. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The CMSKite client.
+ *
+ * Created once and reused. It holds no connection and no mutable state beyond
+ * its configuration, so it is safe to build at module scope and share.
+ *
+ *     const cms = createCMSKite({ apiKey: process.env.CMSKITE_API_KEY! })
+ *     const { items } = await cms.posts.list({ limit: 10 })
+ *
+ * Every method takes an optional `{ signal }`, so a request can be cancelled
+ * when a component unmounts or a newer search supersedes an older one.
+ */
+declare class CMSKite {
+    readonly posts: Posts;
+    readonly categories: Categories;
+    readonly tags: Tags;
+    readonly authors: Authors;
+    /** @internal Not part of the public surface; the shape here may change. */
+    private readonly config;
+    constructor(options: CMSKiteOptions);
+}
+declare class Posts {
+    private readonly config;
+    constructor(config: TransportConfig);
+    /** A page of posts. Published only, newest first, unless you say otherwise. */
+    list(query?: ListPostsQuery, options?: RequestOptions): Promise<Page<Post>>;
+    /** One post by its id. The body is always included. */
+    get(id: string, options?: RequestOptions): Promise<Post>;
+    /**
+     * One post by its address.
+     *
+     * This is what a page at `/blog/[slug]` wants. An old slug still resolves,
+     * and the answer carries `slugRedirectedFrom` so the page can issue a 301
+     * rather than quietly serving two addresses for one post.
+     */
+    getBySlug(slug: string, options?: RequestOptions): Promise<Post>;
+    /**
+     * The same as `getBySlug`, but a missing post is `null` rather than a throw.
+     *
+     * For a page that renders its own not-found state, which is most of them.
+     */
+    findBySlug(slug: string, options?: RequestOptions): Promise<Post | null>;
+    /** Posts like this one, chosen by shared tags and category. */
+    related(id: string, query?: ListQuery, options?: RequestOptions): Promise<Page<Post>>;
+    /** Full-text search across titles and bodies. */
+    search(q: string, query?: ListQuery, options?: RequestOptions): Promise<Page<Post>>;
+    /**
+     * Every post, a page at a time, without writing the cursor loop.
+     *
+     * An async iterator rather than an array, so a site with four thousand posts
+     * does not hold four thousand posts in memory to generate a sitemap.
+     *
+     *     for await (const post of cms.posts.all()) { … }
+     */
+    all(query?: Omit<ListPostsQuery, 'cursor'>, options?: RequestOptions): AsyncGenerator<Post, void, undefined>;
+}
+declare class Categories {
+    private readonly config;
+    constructor(config: TransportConfig);
+    list(query?: ListQuery, options?: RequestOptions): Promise<Page<Category>>;
+    get(id: string, options?: RequestOptions): Promise<Category>;
+}
+declare class Tags {
+    private readonly config;
+    constructor(config: TransportConfig);
+    list(query?: ListQuery, options?: RequestOptions): Promise<Page<Tag>>;
+    get(id: string, options?: RequestOptions): Promise<Tag>;
+}
+declare class Authors {
+    private readonly config;
+    constructor(config: TransportConfig);
+    list(query?: ListQuery, options?: RequestOptions): Promise<Page<Author>>;
+    get(id: string, options?: RequestOptions): Promise<Author>;
+}
+/** Creates a client. The function, rather than `new`, is the documented way in. */
+declare function createCMSKite(options: CMSKiteOptions): CMSKite;
+
+/**
+ * One error type, so a caller writes one catch.
+ *
+ * Everything that can go wrong on the way to an answer arrives as a
+ * `CMSKiteError`: a refusal from the API, a dropped connection, a timeout, a
+ * response that was not JSON. Without that, a `catch` has to tell a `TypeError`
+ * from a `SyntaxError` from whatever the API said, and the ones that forget
+ * show somebody "Failed to fetch" -- a sentence about our code rather than
+ * about their connection.
+ */
+declare class CMSKiteError extends Error {
+    /** HTTP status, or 0 when no response arrived at all. */
+    readonly status: number;
+    /** A stable machine-readable reason. Safe to branch on; see the constants. */
+    readonly code: string;
+    /** Whatever the API attached. Field-level validation problems live here. */
+    readonly details: Record<string, unknown>;
+    /** Quote this when asking us about a request. */
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>, requestId?: string | null);
+    /** Nothing you send differently will change the answer. */
+    get isClientError(): boolean;
+    /** Worth trying again. The client already retried once. */
+    get isRetryable(): boolean;
+    get isNotFound(): boolean;
+    /** The key is missing, wrong, or has been revoked. */
+    get isAuthError(): boolean;
+}
+/**
+ * The codes worth branching on, as values rather than as strings scattered
+ * through a codebase.
+ */
+declare const ErrorCode: {
+    readonly NETWORK: "NETWORK";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly BAD_RESPONSE: "BAD_RESPONSE";
+    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+};
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export { type Author, type BodyFormat, CMSKite, CMSKiteError, type CMSKiteOptions, type Category, ErrorCode, type ErrorCodeValue, type ListPostsQuery, type ListQuery, type Media, type Page, type Pagination, type Post, type PostSort, type PostStatus, type RequestOptions, type Seo, type Tag, createCMSKite };