@stetcms/client 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,12 @@
 # @stetcms/client
 
-Typed client for the [Stet](https://github.com/jamiedavenport/stet) API. The types come straight from the oRPC contract the server implements, so calls and responses are fully typed end to end.
+[![CI](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml/badge.svg)](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-stetcms.com-black.svg)](https://docs.stetcms.com/reference/client)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 
-It also carries the content client runtime that [`@stetcms/vite`](https://github.com/jamiedavenport/stet/tree/main/published/vite)'s generated `stet.gen.ts` instantiates:
+Typed client for the API of [Stet](https://stetcms.com), the CMS where marketing owns the content model and engineering gets a typed client generated from it. The types come straight from the contract the server implements, so calls and responses are fully typed end to end.
+
+It also carries the content client runtime that [`@stetcms/vite`](https://docs.stetcms.com/reference/codegen)'s generated `stet.gen.ts` instantiates:
 
 ```ts
 import { createContentClient } from '@stetcms/client';
@@ -55,14 +59,14 @@ Options:
 - `apiKey`: organization API key sent as `x-api-key`.
 - `fetch`: custom fetch implementation.
 
-The API itself is plain REST under `/api/v1`, described by the OpenAPI document generated from the same contract.
+The API itself is plain REST under `/api/v1`, described by the [OpenAPI document](https://docs.stetcms.com/api) generated from the same contract. [Authentication](https://docs.stetcms.com/api/authentication) covers how keys are scoped.
 
-## License
+## Asset URLs
 
-Apache-2.0
+The API returns asset paths relative to itself; the client joins them to the `origin` it was created with, so what you get is ready for an `img` tag on your own origin. That covers an asset field's `url` and assets embedded or linked inside rich-text markdown and HTML.
 
-## Asset URLs
+Calling the REST API directly instead? `assetUrl(url, origin)` joins one value and `resolveAssetPaths(text, origin)` joins the ones inside rich-text markdown or HTML.
 
-The API returns asset paths relative to itself; the client joins them to the `origin` it was created with, so what you get is ready for an `img` tag on your own origin. That covers both an asset field's `url` and the images inside a rich text body, so a body renders as it stands.
+## License
 
-Calling the REST API directly instead? `assetUrl(url, origin)` joins one value and `resolveAssetPaths(markdown, origin)` joins the ones inside a body.
+Apache-2.0

package/dist/codegen.d.ts

@@ -14,10 +14,13 @@ type ContentModel = {
       options: {
         name: string;
       }[]; /** Slug of the collection a reference field points at. */
-      collection?: string; /** Deleted from the model: emitted as a deprecation, never dropped. */
+      collection?: string;
       deprecated?: {
+        reason: 'deleted' | 'renamed';
         at: string;
         by?: string;
+        note?: string;
+        renamedTo?: string;
       };
     }[];
   }[];

package/dist/codegen.js

@@ -16,7 +16,7 @@ async function fetchContentModel(origin, apiKey) {
 }
 /** `case-studies` → `CaseStudiesEntry`; never starts with a digit. */
 function entryTypeName(slug) {
-	const pascal = slug.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+	const pascal = slug.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 	return /^[A-Za-z]/.test(pascal) ? `${pascal}Entry` : `Stet${pascal}Entry`;
 }
 function optionUnion(options) {
@@ -33,17 +33,19 @@ function fieldTsType(field) {
 		case "asset": return "ContentAsset";
 		case "reference": return "ContentReference";
 		case "multi_reference": return "ContentReference[]";
+		case "rich_text": return "ContentRichText";
 		default: return "string";
 	}
 }
-/**
-* Names the change that retired the key, so whoever meets the strikethrough
-* knows when it happened and who to ask. The date is the ISO day rather than a
-* locale format, which would make the generated file differ between machines.
-*/
 function deprecationNote(deprecation) {
 	const who = deprecation.by === void 0 ? "" : ` by ${deprecation.by}`;
-	return `@deprecated Deleted from the content model on ${deprecation.at.slice(0, 10)}${who}; entries still return the last value it held, until it is purged.`;
+	const when = deprecation.at.slice(0, 10);
+	const context = deprecation.note === void 0 ? "" : ` ${safeDoc(deprecation.note)}`;
+	if (deprecation.reason === "renamed") return `@deprecated Renamed to ${deprecation.renamedTo === void 0 ? "the new key" : `\`${deprecation.renamedTo}\``} on ${when}${who}; this alias returns its current value until the Action is completed.${context}`;
+	return `@deprecated Deleted from the content model on ${when}${who}; entries still return the last value it held until the Action is completed.${context}`;
+}
+function safeDoc(note) {
+	return note.replaceAll("*/", "*\\/").replaceAll(/\s+/g, " ").trim();
 }
 /**
 * What the editor needs that the type cannot say: which collection a reference
@@ -87,6 +89,7 @@ function renderContentModule(model, origin) {
 	const imported = ["ContentEntryBase"];
 	if (fields.some((field) => field.type === "asset")) imported.push("ContentAsset");
 	if (fields.some((field) => field.type === "reference" || field.type === "multi_reference")) imported.push("ContentReference");
+	if (fields.some((field) => field.type === "rich_text")) imported.push("ContentRichText");
 	const lines = [
 		"// Generated by Stet from your content model. Do not edit: it is",
 		"// regenerated by @stetcms/vite or `stet generate`.",

package/dist/index.d.ts

@@ -42,8 +42,14 @@ declare const contentTypeSchema: z.ZodObject<{
     }, z.core.$strip>>;
     collection: z.ZodOptional<z.ZodString>;
     deprecated: z.ZodOptional<z.ZodObject<{
+      reason: z.ZodEnum<{
+        deleted: "deleted";
+        renamed: "renamed";
+      }>;
       at: z.ZodISODateTime;
       by: z.ZodOptional<z.ZodString>;
+      note: z.ZodOptional<z.ZodString>;
+      renamedTo: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -87,6 +93,7 @@ declare const contract: {
         props: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         timestamp: z.ZodNumber;
         url: z.ZodOptional<z.ZodString>;
+        route: z.ZodOptional<z.ZodString>;
         referrer: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
@@ -149,8 +156,14 @@ declare const contract: {
           }, z.core.$strip>>;
           collection: z.ZodOptional<z.ZodString>;
           deprecated: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodEnum<{
+              deleted: "deleted";
+              renamed: "renamed";
+            }>;
             at: z.ZodISODateTime;
             by: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+            renamedTo: z.ZodOptional<z.ZodString>;
           }, z.core.$strip>>;
         }, z.core.$strip>>;
       }, z.core.$strip>>;
@@ -200,8 +213,14 @@ declare const contract: {
           }, z.core.$strip>>;
           collection: z.ZodOptional<z.ZodString>;
           deprecated: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodEnum<{
+              deleted: "deleted";
+              renamed: "renamed";
+            }>;
             at: z.ZodISODateTime;
             by: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+            renamedTo: z.ZodOptional<z.ZodString>;
           }, z.core.$strip>>;
         }, z.core.$strip>>;
       }, z.core.$strip>;
@@ -512,6 +531,11 @@ type ContentAsset = {
   contentType: string; /** Bytes. */
   size: number;
 };
+/** A rich text field rendered canonically by Stet from its editor document. */
+type ContentRichText = {
+  markdown: string;
+  html: string;
+};
 /**
  * The shape `@stetcms/vite` generates from the organization's content model:
  * one key per collection or map, carrying its kind and full entry type.
@@ -545,8 +569,8 @@ type ContentClientOptions = {
  */
 declare function assetUrl(url: string, origin: string): string;
 /**
- * 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.
+ * The same join applied inside a body's markdown or HTML, so an asset an
+ * editor embedded or linked renders on your site as readily as an asset field.
  */
 declare function resolveAssetPaths(text: string, origin: string): string;
 /**
@@ -568,4 +592,4 @@ type StetClientOptions = {
 };
 declare function createStetClient(options?: StetClientOptions): StetClient;
 //#endregion
-export { ApiInputs, ApiOutputs, type CollectionClient, type ContentAsset, type ContentClient, type ContentClientOptions, type ContentEntry, type ContentEntryBase, type ContentModel, type ContentModelShape, type ContentReference, type ContentType, DEFAULT_ORIGIN, type MapClient, type Organization, StetClient, StetClientOptions, assetUrl, createContentClient, createStetClient, entryTypeName, fetchContentModel, isDefinedError, renderContentModule, resolveAssetPaths, safe };
+export { ApiInputs, ApiOutputs, type CollectionClient, type ContentAsset, type ContentClient, type ContentClientOptions, type ContentEntry, type ContentEntryBase, type ContentModel, type ContentModelShape, type ContentReference, type ContentRichText, type ContentType, DEFAULT_ORIGIN, type MapClient, type Organization, StetClient, StetClientOptions, assetUrl, createContentClient, createStetClient, entryTypeName, fetchContentModel, isDefinedError, renderContentModule, resolveAssetPaths, safe };

package/dist/index.js

@@ -166,10 +166,12 @@ const contentFieldTypeSchema = z.enum([
 	"multi_reference"
 ]);
 const contentDeprecationSchema = z.object({
-	/** When the field was deleted from the model. */
+	reason: z.enum(["deleted", "renamed"]),
 	at: z.iso.datetime(),
-	/** Who deleted it; absent when no signed-in user did, or the account is gone. */
-	by: z.string().optional()
+	by: z.string().optional(),
+	note: z.string().optional(),
+	/** Current canonical key, present for a rename. */
+	renamedTo: z.string().optional()
 });
 const contentFieldSchema = z.object({
 	key: z.string(),
@@ -183,14 +185,8 @@ const contentFieldSchema = z.object({
 	/** 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.
+	* Present for deleted fields and old rename aliases. Entries keep returning
+	* the value through this key until its Action is completed.
 	*/
 	deprecated: contentDeprecationSchema.optional()
 });
@@ -214,7 +210,7 @@ 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.",
+	description: "Every collection and map in the organization with its fields. The generated client is typed from this. Deleted fields and old rename aliases carry a `deprecated` record so regeneration keeps downstream clients compiling until the matching Action is completed.",
 	tags: ["Content"]
 }).output(z.object({ types: z.array(contentTypeSchema) }));
 const listContent = oc.errors({
@@ -224,7 +220,7 @@ const listContent = oc.errors({
 	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.",
+	description: "A content type's entries with resolved field values; rich text bodies contain canonical HTML and markdown. A map returns its single entry as a one-element list.",
 	tags: ["Content"]
 }).input(z.object({ type: z.string() })).output(z.object({
 	type: contentTypeSchema,
@@ -268,6 +264,8 @@ const analyticsEventSchema = z.object({
 	/** Epoch milliseconds, stamped in the browser when the event happened. */
 	timestamp: z.number().int().nonnegative(),
 	url: z.string().optional(),
+	/** Router template for the URL, e.g. `/blog/[slug]`. */
+	route: z.string().min(1).max(500).optional(),
 	referrer: z.string().optional()
 });
 const contract = {
@@ -324,10 +322,10 @@ const assetPath = "/assets/";
 function assetUrl(url, origin) {
 	return url.startsWith(assetPath) ? `${origin}${url}` : url;
 }
-const assetPathInText = /(\]\(|src=["'])(\/assets\/)/g;
+const assetPathInText = /(\]\(|\s(?:src|href)=["'])(\/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.
+* The same join applied inside a body's markdown or HTML, so an asset an
+* editor embedded or linked renders on your site as readily as an asset field.
 */
 function resolveAssetPaths(text, origin) {
 	return text.replace(assetPathInText, (_match, prefix) => `${prefix}${origin}${assetPath}`);

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@stetcms/client",
-  "version": "0.1.0",
-  "description": "Typed client for the Stet API, generated from the oRPC contract.",
+  "version": "0.2.0",
+  "description": "Typed content and REST client for Stet, the CMS for marketing and engineering.",
   "keywords": [
     "api",
     "client",
-    "orpc",
-    "stet"
+    "cms",
+    "content-api",
+    "headless-cms",
+    "sdk",
+    "stet",
+    "stetcms",
+    "typesafe",
+    "typescript"
   ],
-  "homepage": "https://github.com/jamiedavenport/stet/tree/main/published/client#readme",
+  "homepage": "https://docs.stetcms.com/reference/client",
   "bugs": "https://github.com/jamiedavenport/stet/issues",
   "license": "Apache-2.0",
   "author": "Jamie Davenport (https://jxd.dev)",
@@ -21,6 +27,7 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,7 +46,7 @@
     "@orpc/contract": "^1.14.8",
     "@orpc/openapi-client": "^1.14.8",
     "zod": "^4.4.3",
-    "@stetcms/config": "0.1.0"
+    "@stetcms/config": "0.1.1"
   },
   "devDependencies": {
     "publint": "^0.3.21",
@@ -48,6 +55,9 @@
     "vitest": "^4.1.9",
     "@repo/api": "0.0.0"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "vp pack",
     "tc": "tsc --noEmit",