cmskite 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,204 @@
+import { CMSKiteError, ErrorCode, DEFAULT_BASE_URL, request } from './chunk-DT3V5CH2.js';
+export { CMSKiteError, ErrorCode } from './chunk-DT3V5CH2.js';
+
+// 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);
+}
+
+export { CMSKite, createCMSKite };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["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/react.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+var react = require('react');
+
+// src/transport.ts
+var DEFAULT_BASE_URL = "https://api.cmskite.com";
+
+// src/analytics.ts
+var MAX_BATCH = 50;
+var STORAGE_PREFIX = "cmskite:v:";
+var CMSKiteAnalytics = class {
+  endpoint;
+  apiKey;
+  enabled;
+  flushIntervalMs;
+  fetchImpl;
+  queue = [];
+  timer = null;
+  listening = false;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.endpoint = `${(options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "")}/v1/blog/events`;
+    this.enabled = options.enabled !== false;
+    this.flushIntervalMs = options.flushIntervalMs ?? 1e3;
+    this.fetchImpl = options.fetch;
+    this.listenForUnload();
+  }
+  /**
+   * One reader seeing one post.
+   *
+   * Call it when the post is rendered. Calling it again for the same post in
+   * the same tab does nothing, which is what makes it safe to put in a React
+   * effect that runs on every render.
+   */
+  trackView(postId, path) {
+    if (!this.enabled || !postId) return;
+    if (this.alreadySeen(postId)) return;
+    this.remember(postId);
+    this.push({ type: "view", postId, ...path ? { path } : { path: currentPath() } });
+  }
+  /**
+   * A link press.
+   *
+   * Not deduplicated: pressing the same link twice is two clicks, and the nonce
+   * is what tells the server so.
+   */
+  trackClick(postId, target, path) {
+    if (!this.enabled || !postId) return;
+    this.push({
+      type: "click",
+      postId,
+      ...target ? { target: target.slice(0, 300) } : {},
+      ...path ? { path } : { path: currentPath() },
+      nonce: nonce()
+    });
+  }
+  /** Sends whatever is queued now. Called for you on page hide. */
+  flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, MAX_BATCH);
+    this.clearTimer();
+    this.send(batch);
+  }
+  /** Stops the timer and the listeners. For a test, or a single-page teardown. */
+  destroy() {
+    this.flush();
+    this.clearTimer();
+  }
+  // --- internals ------------------------------------------------------------
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= MAX_BATCH) return this.flush();
+    if (!this.timer) {
+      this.timer = setTimeout(() => this.flush(), this.flushIntervalMs);
+      this.timer.unref?.();
+    }
+  }
+  send(events) {
+    const body = JSON.stringify({ events });
+    if (!this.fetchImpl) {
+      try {
+        if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+          const url = `${this.endpoint}?key=${encodeURIComponent(this.apiKey)}`;
+          const blob = new Blob([body], { type: "application/json" });
+          if (navigator.sendBeacon(url, blob)) return;
+        }
+      } catch {
+      }
+    }
+    try {
+      void (this.fetchImpl ?? fetch)(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${this.apiKey}` },
+        body,
+        // Survives the navigation that triggered it, like sendBeacon does.
+        keepalive: true
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  /**
+   * What this tab has already reported.
+   *
+   * `sessionStorage`, not `localStorage`: a view should be counted again
+   * tomorrow, and a session is the unit the server deduplicates on too. A
+   * browser that refuses storage -- private mode, blocked site data -- falls
+   * back to counting the view, which is the right way to be wrong.
+   */
+  alreadySeen(postId) {
+    try {
+      return sessionStorage.getItem(STORAGE_PREFIX + postId) !== null;
+    } catch {
+      return false;
+    }
+  }
+  remember(postId) {
+    try {
+      sessionStorage.setItem(STORAGE_PREFIX + postId, "1");
+    } catch {
+    }
+  }
+  listenForUnload() {
+    if (this.listening || typeof document === "undefined") return;
+    this.listening = true;
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") this.flush();
+    });
+  }
+  clearTimer() {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+function currentPath() {
+  try {
+    return window.location.pathname;
+  } catch {
+    return "/";
+  }
+}
+function nonce() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// src/react.ts
+function useTrackView(postId, options) {
+  const tracker = useTracker(options);
+  const reported = react.useRef(null);
+  react.useEffect(() => {
+    if (!postId || reported.current === postId) return;
+    reported.current = postId;
+    tracker.trackView(postId);
+  }, [postId, tracker]);
+}
+function useCMSKiteAnalytics(options) {
+  return useTracker(options);
+}
+function useTracker(options) {
+  const { apiKey, baseUrl, enabled, flushIntervalMs } = options;
+  return react.useMemo(
+    () => new CMSKiteAnalytics({
+      apiKey,
+      ...baseUrl === void 0 ? {} : { baseUrl },
+      ...enabled === void 0 ? {} : { enabled },
+      ...flushIntervalMs === void 0 ? {} : { flushIntervalMs }
+    }),
+    [apiKey, baseUrl, enabled, flushIntervalMs]
+  );
+}
+
+exports.useCMSKiteAnalytics = useCMSKiteAnalytics;
+exports.useTrackView = useTrackView;
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map