src/client.ts

Functions

Imports

It imports src/contract.ts, src/local.ts. Imported by src/admin/kit.ts, src/admin/media.ts, src/admin/posts.ts, src/local.ts.

Source

1// The Carrel side: a typed client for one site. Every response is checked against the contract, so
2// a site that drifts fails here by name instead of somewhere later in Carrel.
3
4import type { z } from "zod";
5import {
6  ContentDeleteResult,
7  ContentDoc,
8  ContentList,
9  Diff,
10  ErrorBody,
11  MediaBulkResult,
12  MediaDeleteResult,
13  MediaDetail,
14  MediaItem,
15  MediaList,
16  MediaTrashEmptyResult,
17  MediaWriteResult,
18  MentionDecideInput,
19  MentionDeleteResult,
20  MentionList,
21  MentionSweepResult,
22  MentionWriteResult,
23  Meta,
24  PREFIX,
25  RevisionList,
26  RevisionSource,
27  WriteResult,
28  type ContentTagsInput,
29  type ListQuery,
30  type MediaAltInput,
31  type MediaBulkInput,
32  type MediaListQuery,
33  type MediaTagsInput,
34  type MediaTrashEmptyInput,
35  type MediaTrashInput,
36  type MentionListQuery,
37  type PreviewInput,
38  type PublishInput,
39  type SaveDraftInput,
40  type ScheduleInput,
41  type UnpublishInput,
42} from "./contract.js";
43
44export interface SiteClientConfig {
45  /** The site's origin, such as https://dustinedwards.info. */
46  baseUrl: string;
47  key: string;
48  fetch?: typeof fetch;
49}
50
51/** A refusal or failure from the site, with the contract's error body when the site sent one. */
52export class SiteApiError extends Error {
53  constructor(
54    readonly status: number,
55    readonly body: ErrorBody | null,
56  ) {
57    super(body ? `${status} ${body.error}: ${body.message}` : `site answered ${status}`);
58    this.name = "SiteApiError";
59  }
60}
61
62export function createSiteClient(config: SiteClientConfig) {
63  const doFetch = config.fetch ?? fetch;
64  const base = `${config.baseUrl.replace(/\/+$/, "")}${PREFIX}`;
65  const enc = encodeURIComponent;
66
67  async function call(method: string, path: string, body?: unknown, raw?: { bytes: Uint8Array; contentType: string }): Promise<Response> {
68    const response = await doFetch(`${base}${path}`, {
69      method,
70      headers: {
71        authorization: `Bearer ${config.key}`,
72        ...(raw ? { "content-type": raw.contentType } : body === undefined ? {} : { "content-type": "application/json" }),
73      },
74      // A Blob, which every fetch takes as a body whatever its buffer type.
75      body: raw ? new Blob([raw.bytes as Uint8Array<ArrayBuffer>]) : body === undefined ? undefined : JSON.stringify(body),
76    });
77    if (!response.ok) {
78      let parsed: ErrorBody | null = null;
79      try {
80        const result = ErrorBody.safeParse(await response.json());
81        if (result.success) parsed = result.data;
82      } catch {
83        // Not JSON: the site's own error page, not ours.
84      }
85      throw new SiteApiError(response.status, parsed);
86    }
87    return response;
88  }
89
90  async function get<T extends z.ZodType>(schema: T, method: string, path: string, body?: unknown) {
91    return schema.parse(await (await call(method, path, body)).json()) as z.infer<T>;
92  }
93
94  function query(params: Record<string, string | number | undefined>): string {
95    const search = new URLSearchParams();
96    for (const [k, v] of Object.entries(params)) if (v !== undefined) search.set(k, String(v));
97    const text = search.toString();
98    return text ? `?${text}` : "";
99  }
100
101  return {
102    meta: () => get(Meta, "GET", "/meta"),
103    list: (q: Partial<ListQuery> = {}) => get(ContentList, "GET", `/content${query(q)}`),
104    get: (id: string) => get(ContentDoc, "GET", `/content/${enc(id)}`),
105    saveDraft: (id: string, input: SaveDraftInput) => get(WriteResult, "PUT", `/content/${enc(id)}/draft`, input),
106    publish: (id: string, input: PublishInput) => get(WriteResult, "POST", `/content/${enc(id)}/publish`, input),
107    schedule: (id: string, input: ScheduleInput) => get(WriteResult, "POST", `/content/${enc(id)}/schedule`, input),
108    unpublish: (id: string, input: UnpublishInput) => get(WriteResult, "POST", `/content/${enc(id)}/unpublish`, input),
109    revisions: (id: string) => get(RevisionList, "GET", `/content/${enc(id)}/revisions`),
110    /** One revision's source (v0.3.0), so each revision in the list opens. */
111    revision: (id: string, version: string) => get(RevisionSource, "GET", `/content/${enc(id)}/revisions/${enc(version)}`),
112    /** Optional per site (v0.3.0): a site with no delete answers SiteApiError with status 501. */
113    delete: (id: string, input: { expectedVersion: string; changeId: string }) =>
114      get(ContentDeleteResult, "DELETE", `/content/${enc(id)}${query(input)}`),
115    /** Optional per site (v0.6.0): sets a post's whole tag set. A site without it answers SiteApiError with status 501. */
116    setTags: (id: string, input: ContentTagsInput) => get(WriteResult, "PUT", `/content/${enc(id)}/tags`, input),
117    diff: (id: string, from: string, to?: string) => get(Diff, "GET", `/content/${enc(id)}/diff${query({ from, to })}`),
118    preview: async (input: PreviewInput) => (await call("POST", "/preview", input)).text(),
119    /** The media group (v0.2.0). A refused delete throws SiteApiError whose body carries `usedBy`. */
120    media: {
121      list: (q: Partial<MediaListQuery> = {}) => get(MediaList, "GET", `/media${query(q)}`),
122      get: (id: string) => get(MediaDetail, "GET", `/media/${enc(id)}`),
123      upload: async (input: { bytes: Uint8Array; contentType: string; filename: string; alt?: string; changeId: string }) =>
124        MediaItem.parse(
125          await (
126            await call("POST", `/media${query({ filename: input.filename, alt: input.alt, changeId: input.changeId })}`, undefined, {
127              bytes: input.bytes,
128              contentType: input.contentType,
129            })
130          ).json(),
131        ),
132      /** Takes `{ changeId }` (v0.6.0), like every other write; the change id alone still works. */
133      delete: (id: string, input: { changeId: string } | string) =>
134        get(MediaDeleteResult, "DELETE", `/media/${enc(id)}${query({ changeId: typeof input === "string" ? input : input.changeId })}`),
135      /**
136       * The writes of v0.4.0, each optional per site: a site without it answers SiteApiError with
137       * status 501 (see meta().capabilities). A stale version is status 409 with the current version.
138       */
139      setAlt: (id: string, input: MediaAltInput) => get(MediaWriteResult, "PUT", `/media/${enc(id)}/alt`, input),
140      setTags: (id: string, input: MediaTagsInput) => get(MediaWriteResult, "PUT", `/media/${enc(id)}/tags`, input),
141      trash: (id: string, input: MediaTrashInput) => get(MediaWriteResult, "POST", `/media/${enc(id)}/trash`, input),
142      restore: (id: string, input: MediaTrashInput) => get(MediaWriteResult, "POST", `/media/${enc(id)}/restore`, input),
143      /** Deletes for good every trashed file the site allows, up to MAX_TRASH_EMPTY; `more` says to send it again. */
144      emptyTrash: (input: MediaTrashEmptyInput) => get(MediaTrashEmptyResult, "POST", "/media/trash/empty", input),
145      /** One request for many files; every file's outcome is its own, so check each `ok`. */
146      bulk: (input: MediaBulkInput) => get(MediaBulkResult, "POST", "/media/bulk", input),
147    },
148    /** The mentions group (v0.5.0), optional per site: a site without it answers SiteApiError with status 501. */
149    mentions: {
150      list: (q: Partial<MentionListQuery> = {}) => get(MentionList, "GET", `/mentions${query(q)}`),
151      decide: (id: string, input: MentionDecideInput) => get(MentionWriteResult, "POST", `/mentions/${enc(id)}/decide`, input),
152      delete: (id: string, input: { expectedVersion: string; changeId: string }) =>
153        get(MentionDeleteResult, "DELETE", `/mentions/${enc(id)}${query(input)}`),
154      /** Takes `{ changeId }` (v0.6.0), like every other write; the change id alone still works. */
155      sweep: (input: { changeId: string } | string) =>
156        get(MentionSweepResult, "POST", "/mentions/sweep", { changeId: typeof input === "string" ? input : input.changeId }),
157    },
158  };
159}
160
161export type SiteClient = ReturnType<typeof createSiteClient>;
162
163// A site's own admin: the same client, answered in process by its own adapter (./local.ts).
164export { localClient, type LocalClientOptions } from "./local.js";