@stetcms/client 0.1.0

package/dist/index.js

@@ -0,0 +1,397 @@
+import { DEFAULT_ORIGIN, entryTypeName, fetchContentModel, renderContentModule } from "./codegen.js";
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { createORPCClient, isDefinedError, safe } from "@orpc/client";
+import { OpenAPILink } from "@orpc/openapi-client/fetch";
+//#region ../../internal/api/src/contract.ts
+const organizationSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	logo: z.string().nullable(),
+	createdAt: z.iso.datetime()
+});
+const rateLimitError = { RATE_LIMITED: {
+	status: 429,
+	message: "Too many requests. Try again shortly."
+} };
+const authErrors = {
+	UNAUTHORIZED: { message: "Authentication required. Pass an organization API key in the `x-api-key` header." },
+	QUOTA_EXCEEDED: {
+		status: 429,
+		message: "The organization's API request limit for this period has been reached."
+	},
+	...rateLimitError
+};
+const health = oc.errors(rateLimitError).route({
+	method: "GET",
+	path: "/health",
+	summary: "Health check",
+	description: "Public liveness probe. Returns ok when the API is reachable.",
+	tags: ["System"]
+}).output(z.object({ status: z.literal("ok") }));
+const getOrg = oc.errors(authErrors).route({
+	method: "GET",
+	path: "/org",
+	summary: "Current organization",
+	description: "Details of the organization the API key is scoped to.",
+	tags: ["Organization"]
+}).output(organizationSchema);
+const usageSchema = z.object({
+	feature: z.enum([
+		"members",
+		"apiRequests",
+		"storage"
+	]),
+	used: z.number().int(),
+	cap: z.number().int().nullable(),
+	window: z.enum(["month"]).nullable()
+});
+const orgBillingSchema = z.object({
+	plan: z.enum(["free", "paid"]),
+	status: z.string().nullable(),
+	seats: z.number().int().nullable(),
+	periodEnd: z.iso.datetime().nullable(),
+	cancelAtPeriodEnd: z.boolean(),
+	usage: z.array(usageSchema)
+});
+const getOrgBilling = oc.errors(authErrors).route({
+	method: "GET",
+	path: "/org/billing",
+	summary: "Organization billing",
+	description: "The organization's plan, subscription state, and usage against the plan's limits.",
+	tags: ["Organization"]
+}).output(orgBillingSchema);
+const noteSchema = z.object({
+	/** The note as plain text, one line per block. Null until the room first saves. */
+	text: z.string().nullable(),
+	words: z.number().int(),
+	savedAt: z.iso.datetime().nullable()
+});
+const getNote = oc.errors(authErrors).route({
+	method: "GET",
+	path: "/org/notes",
+	summary: "Shared note",
+	description: "The organization's collaborative note as last saved by the realtime room. It trails live editing by a few seconds, so `savedAt` says which version this is.",
+	tags: ["Organization"]
+}).output(noteSchema);
+const webhookEventTypeSchema = z.enum([
+	"content.changed",
+	"member.joined",
+	"invitation.created",
+	"subscription.started",
+	"subscription.canceled",
+	"ping"
+]);
+const webhookEndpointSchema = z.object({
+	id: z.string(),
+	url: z.string(),
+	events: z.array(webhookEventTypeSchema),
+	enabled: z.boolean(),
+	createdAt: z.iso.datetime()
+});
+const webhookEndpointWithSecretSchema = webhookEndpointSchema.extend({ secret: z.string() });
+const webhookDeliverySchema = z.object({
+	id: z.string(),
+	eventId: z.string(),
+	eventType: z.string(),
+	status: z.enum(["success", "failed"]),
+	responseStatus: z.number().int().nullable(),
+	attempts: z.number().int(),
+	createdAt: z.iso.datetime()
+});
+const webhookNotFound = { NOT_FOUND: { message: "No webhook endpoint with that id in this organization." } };
+const listWebhooks = oc.errors(authErrors).route({
+	method: "GET",
+	path: "/webhooks",
+	summary: "List webhook endpoints",
+	description: "The organization's webhook endpoints, without their signing secrets.",
+	tags: ["Webhooks"]
+}).output(z.array(webhookEndpointSchema));
+const createWebhook = oc.errors({
+	...authErrors,
+	BAD_REQUEST: { message: "Webhook URLs must be https (plain http is allowed for localhost)." }
+}).route({
+	method: "POST",
+	path: "/webhooks",
+	summary: "Create a webhook endpoint",
+	description: "Registers an endpoint for the given event types. The response includes the signing secret; verify deliveries with any Standard Webhooks library.",
+	tags: ["Webhooks"]
+}).input(z.object({
+	url: z.url(),
+	events: z.array(webhookEventTypeSchema).min(1)
+})).output(webhookEndpointWithSecretSchema);
+const deleteWebhook = oc.errors({
+	...authErrors,
+	...webhookNotFound
+}).route({
+	method: "DELETE",
+	path: "/webhooks/{id}",
+	summary: "Delete a webhook endpoint",
+	description: "Removes the endpoint and its delivery history.",
+	tags: ["Webhooks"]
+}).input(z.object({ id: z.string() })).output(z.object({ id: z.string() }));
+const rotateWebhookSecret = oc.errors({
+	...authErrors,
+	...webhookNotFound
+}).route({
+	method: "POST",
+	path: "/webhooks/{id}/rotate-secret",
+	summary: "Rotate a webhook signing secret",
+	description: "Issues a new signing secret. The previous secret keeps signing deliveries for 24 hours so receivers can roll over without downtime.",
+	tags: ["Webhooks"]
+}).input(z.object({ id: z.string() })).output(webhookEndpointWithSecretSchema);
+const listWebhookDeliveries = oc.errors({
+	...authErrors,
+	...webhookNotFound
+}).route({
+	method: "GET",
+	path: "/webhooks/{id}/deliveries",
+	summary: "List recent deliveries",
+	description: "The most recent delivery attempts for the endpoint, newest first.",
+	tags: ["Webhooks"]
+}).input(z.object({ id: z.string() })).output(z.array(webhookDeliverySchema));
+const contentFieldTypeSchema = z.enum([
+	"text",
+	"rich_text",
+	"number",
+	"checkbox",
+	"date",
+	"select",
+	"multi_select",
+	"link",
+	"person",
+	"asset",
+	"reference",
+	"multi_reference"
+]);
+const contentDeprecationSchema = z.object({
+	/** When the field was deleted from the model. */
+	at: z.iso.datetime(),
+	/** Who deleted it; absent when no signed-in user did, or the account is gone. */
+	by: z.string().optional()
+});
+const contentFieldSchema = z.object({
+	key: z.string(),
+	name: z.string(),
+	type: contentFieldTypeSchema,
+	/** Choices of a select or multi-select field; empty for other types. */
+	options: z.array(z.object({
+		name: z.string(),
+		color: z.string()
+	})),
+	/** Slug of the collection a reference or multi-reference field points at. */
+	collection: z.string().optional(),
+	/**
+	* Present once the field has been deleted from the model, naming when and
+	* by whom so a stale key can be traced back to the change that retired it.
+	* Editors stop seeing the field, but entries keep the last value it held
+	* and go on returning it, so a deletion costs a running site nothing. A
+	* generated client turns it into a deprecation rather than dropping the
+	* key, so code reading it keeps compiling. The key and its values go for
+	* good only when a developer purges the field from the Danger Zone, after
+	* which it leaves this list.
+	*/
+	deprecated: contentDeprecationSchema.optional()
+});
+const contentTypeSchema = z.object({
+	slug: z.string(),
+	name: z.string(),
+	/** A collection holds many entries; a map holds exactly one. */
+	kind: z.enum(["collection", "map"]),
+	fields: z.array(contentFieldSchema)
+});
+const contentEntrySchema = z.object({
+	id: z.string(),
+	slug: z.string(),
+	title: z.string(),
+	fields: z.record(z.string(), z.unknown()),
+	createdAt: z.iso.datetime(),
+	updatedAt: z.iso.datetime()
+});
+const contentNotFound = { NOT_FOUND: { message: "No content type with that slug in this organization." } };
+const getContentModel = oc.errors(authErrors).route({
+	method: "GET",
+	path: "/model",
+	summary: "Content model",
+	description: "Every collection and map in the organization with its fields. The generated client is typed from this. Deleted fields are still listed, carrying a `deprecated` record of when and by whom, so a client regenerated after a deletion marks the key instead of dropping it and entries go on returning the last value it held.",
+	tags: ["Content"]
+}).output(z.object({ types: z.array(contentTypeSchema) }));
+const listContent = oc.errors({
+	...authErrors,
+	...contentNotFound
+}).route({
+	method: "GET",
+	path: "/content/{type}",
+	summary: "List entries",
+	description: "A content type's entries with resolved field values; rich text bodies are markdown as last saved by the realtime room. A map returns its single entry as a one-element list.",
+	tags: ["Content"]
+}).input(z.object({ type: z.string() })).output(z.object({
+	type: contentTypeSchema,
+	entries: z.array(contentEntrySchema)
+}));
+const getContent = oc.errors({
+	...authErrors,
+	NOT_FOUND: { message: "No such content type or entry in this organization." }
+}).route({
+	method: "GET",
+	path: "/content/{type}/{slug}",
+	summary: "Get one entry",
+	description: "One entry of a collection, addressed by its slug.",
+	tags: ["Content"]
+}).input(z.object({
+	type: z.string(),
+	slug: z.string()
+})).output(contentEntrySchema);
+const analyticsMetadataSchema = z.object({
+	/** Day-scoped visitor digest computed by the caller. Never an address. */
+	visitor: z.string().optional(),
+	country: z.string().optional(),
+	region: z.string().optional(),
+	city: z.string().optional(),
+	browser: z.string().optional(),
+	os: z.string().optional(),
+	device: z.enum([
+		"desktop",
+		"mobile",
+		"tablet"
+	]).optional()
+});
+const analyticsErrors = {
+	UNAUTHORIZED: authErrors.UNAUTHORIZED,
+	...rateLimitError
+};
+const analyticsEventSchema = z.object({
+	/** `$pageview`, or an event from the organization's tracking plan. */
+	name: z.string().min(1).max(120),
+	props: z.record(z.string(), z.unknown()).default({}),
+	/** Epoch milliseconds, stamped in the browser when the event happened. */
+	timestamp: z.number().int().nonnegative(),
+	url: z.string().optional(),
+	referrer: z.string().optional()
+});
+const contract = {
+	health,
+	analytics: {
+		ingest: oc.errors(analyticsErrors).route({
+			method: "POST",
+			path: "/events",
+			summary: "Record events",
+			description: "Stores a batch of analytics events. Sent by the handler you mounted in your own app, which validates them against your tracking plan first. Query strings are reduced to their campaign parameters on the way in.",
+			tags: ["Analytics"]
+		}).input(z.object({
+			context: z.record(z.string(), z.unknown()).default({}),
+			metadata: analyticsMetadataSchema.default({}),
+			events: z.array(analyticsEventSchema).min(1).max(100)
+		})).output(z.object({ accepted: z.number().int() })),
+		sync: oc.errors(analyticsErrors).route({
+			method: "PUT",
+			path: "/events/schema",
+			summary: "Publish the tracking plan",
+			description: "Replaces the organization's known events with the ones your code declares, so the dashboard can offer them. Sent by @stetcms/vite and `stet sync`.",
+			tags: ["Analytics"]
+		}).input(z.object({ events: z.array(z.object({
+			name: z.string().min(1),
+			props: z.array(z.string())
+		})) })).output(z.object({ synced: z.number().int() }))
+	},
+	content: {
+		model: getContentModel,
+		list: listContent,
+		get: getContent
+	},
+	org: {
+		current: getOrg,
+		billing: getOrgBilling,
+		note: getNote
+	},
+	webhooks: {
+		list: listWebhooks,
+		create: createWebhook,
+		delete: deleteWebhook,
+		rotateSecret: rotateWebhookSecret,
+		deliveries: listWebhookDeliveries
+	}
+};
+//#endregion
+//#region src/content.ts
+/** The path the API serves public content assets from. */
+const assetPath = "/assets/";
+/**
+* Joins an asset path to the Stet origin. Anything already absolute is left
+* alone, so a future API that returns whole URLs needs no change here.
+*/
+function assetUrl(url, origin) {
+	return url.startsWith(assetPath) ? `${origin}${url}` : url;
+}
+const assetPathInText = /(\]\(|src=["'])(\/assets\/)/g;
+/**
+* The same join applied inside a body's markdown, so an image an editor
+* dropped into a body renders on your site as readily as an asset field does.
+*/
+function resolveAssetPaths(text, origin) {
+	return text.replace(assetPathInText, (_match, prefix) => `${prefix}${origin}${assetPath}`);
+}
+/**
+* Rewrites every asset URL in a response to a whole URL: an asset field's
+* value, and the images an editor dropped into a rich text body.
+*
+* The API returns them relative to itself, because it is the same bytes
+* whichever origin serves them and baking one in would pin stored content to
+* a domain. Your site is a different origin, so a relative path would resolve
+* against yours; the client owns the join because the origin is exactly what
+* it was configured with.
+*/
+function resolveAssetUrls(payload, origin) {
+	if (Array.isArray(payload)) return payload.map((item) => resolveAssetUrls(item, origin));
+	if (typeof payload !== "object" || payload === null) return payload;
+	const entries = Object.entries(payload).map(([key, value]) => {
+		if (typeof value === "string") return [key, key === "url" ? assetUrl(value, origin) : resolveAssetPaths(value, origin)];
+		return [key, resolveAssetUrls(value, origin)];
+	});
+	return Object.fromEntries(entries);
+}
+/**
+* The model-shaped client `stet.gen.ts` instantiates: `stet.posts.list()`,
+* `stet.posts.get('hello-world')`, `stet.landing.get()`. The type parameter
+* narrows which keys exist and what their entries look like; the runtime is
+* one Proxy over the content API.
+*/
+function createContentClient(options = {}) {
+	const origin = options.origin ?? DEFAULT_ORIGIN;
+	const request = async (path) => {
+		const response = await (options.fetch ?? globalThis.fetch)(`${origin}/api/v1${path}`, { headers: options.apiKey === void 0 ? {} : { "x-api-key": options.apiKey } });
+		if (!response.ok) throw new Error(`Stet request ${path} failed with status ${response.status}.`);
+		return resolveAssetUrls(await response.json(), origin);
+	};
+	const listEntries = async (slug) => {
+		return (await request(`/content/${encodeURIComponent(slug)}`)).entries;
+	};
+	const clientFor = (slug) => ({
+		list: () => listEntries(slug),
+		get: async (entrySlug) => {
+			if (entrySlug !== void 0) return request(`/content/${encodeURIComponent(slug)}/${encodeURIComponent(entrySlug)}`);
+			const [entry] = await listEntries(slug);
+			if (entry === void 0) throw new Error(`Map "${slug}" has no entry.`);
+			return entry;
+		}
+	});
+	return new Proxy({}, { get: (_target, property) => {
+		if (typeof property !== "string" || property === "then") return;
+		return clientFor(property);
+	} });
+}
+//#endregion
+//#region src/index.ts
+function createStetClient(options = {}) {
+	return createORPCClient(new OpenAPILink(contract, {
+		url: `${options.origin ?? DEFAULT_ORIGIN}/api/v1`,
+		headers: () => {
+			if (options.apiKey === void 0) return {};
+			return { "x-api-key": options.apiKey };
+		},
+		fetch: options.fetch
+	}));
+}
+//#endregion
+export { DEFAULT_ORIGIN, assetUrl, createContentClient, createStetClient, entryTypeName, fetchContentModel, isDefinedError, renderContentModule, resolveAssetPaths, safe };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@stetcms/client",
+  "version": "0.1.0",
+  "description": "Typed client for the Stet API, generated from the oRPC contract.",
+  "keywords": [
+    "api",
+    "client",
+    "orpc",
+    "stet"
+  ],
+  "homepage": "https://github.com/jamiedavenport/stet/tree/main/published/client#readme",
+  "bugs": "https://github.com/jamiedavenport/stet/issues",
+  "license": "Apache-2.0",
+  "author": "Jamie Davenport (https://jxd.dev)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamiedavenport/stet.git",
+    "directory": "published/client"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "default": "./dist/codegen.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@orpc/client": "^1.14.8",
+    "@orpc/contract": "^1.14.8",
+    "@orpc/openapi-client": "^1.14.8",
+    "zod": "^4.4.3",
+    "@stetcms/config": "0.1.0"
+  },
+  "devDependencies": {
+    "publint": "^0.3.21",
+    "typescript": "^5.9.3",
+    "vite-plus": "0.2.2",
+    "vitest": "^4.1.9",
+    "@repo/api": "0.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "tc": "tsc --noEmit",
+    "test": "vp test run"
+  }
+}