@rootsmithio/client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidewave Digital Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# RootSmith client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read and render published RootSmith pages in any JavaScript framework, and
+answer the signed refresh that RootSmith sends when you publish. It uses only
+the standard `fetch`, `Request`, and `Response` objects. For Next.js, use
+[`@rootsmithio/next`](../next), which wraps this package with the Next.js
+cache, redirects, and metadata.
+
+The package is built in this workspace. It has not been released to npm.
+
+## Read pages
+
+```ts
+import { createRootSmith } from "@rootsmithio/client"
+
+export const rootSmith = createRootSmith({
+  apiUrl: process.env.ROOTSMITH_API_URL!,
+  siteId: process.env.ROOTSMITH_SITE_ID!,
+})
+```
+
+- `getPage(path)` returns the published page, `null` for a missing page or
+  an unsupported path, or `{ redirect }` when the page was merged into
+  another page. Send a 308 redirect for that case.
+- `listPages(page)` returns up to 25 pages, sorted by path. `listAllPages()`
+  returns every published page.
+- `init` adds request options, such as a framework cache setting, to each
+  read. Reads never follow redirects and time out after 10 seconds.
+
+## Render a page
+
+`renderHtml(page, { imageOrigins })` returns the page body as HTML inside a
+`div` with the `rootsmith-markdown` class and the content/version attributes
+used for live confirmation. It supports GitHub Flavored Markdown. Raw HTML is
+removed, unsafe URL schemes are dropped, relative links resolve against the
+page URL, and images load only from the page's origin or the listed origins.
+
+## Refresh
+
+```ts
+import { createRootSmithHandler } from "@rootsmithio/client"
+
+const handler = createRootSmithHandler({
+  refresh: (path) => cache.delete(path),
+})
+export const POST = ({ request }: { request: Request }) => handler(request)
+```
+
+The handler reads `ROOTSMITH_SITE_ID` and `ROOTSMITH_CONNECTION_SECRET` from
+`process.env` when a request arrives, or uses `siteId` and `secret`. It
+answers 503 until both are set. It checks the site, the timestamp, and the
+HMAC signature, calls `refresh` for a refresh request, and signs its
+response. `refresh` must finish before the handler returns.
+
+## Verification
+
+`pnpm --filter @rootsmithio/client test` checks rendering, sanitizing,
+redirects, request options, and signed refresh requests.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { PublishedPage } from "./page.js";
+export type { PublishedPage } from "./page.js";
+export { originOf, safeContentUrl } from "./url.js";
+export declare function createRootSmith({ apiUrl, siteId, fetcher, init, }: {
+    apiUrl: string;
+    siteId: string;
+    fetcher?: typeof fetch;
+    init?: () => RequestInit;
+}): {
+    listPages: (page?: number) => Promise<PublishedPage[]>;
+    listAllPages(): Promise<PublishedPage[]>;
+    getPage(path: string): Promise<PublishedPage | {
+        redirect: string;
+    } | null>;
+};
+export declare function createRootSmithHandler({ siteId: configuredSiteId, secret: configuredSecret, refresh, }?: {
+    siteId?: string;
+    secret?: string;
+    refresh?: (path: string) => void | Promise<void>;
+}): (request: Request) => Promise<Response>;
+export declare function renderHtml(page: Pick<PublishedPage, "id" | "revision" | "markdown" | "url">, { imageOrigins }?: {
+    imageOrigins?: string[];
+}): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAG9C,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAEnD,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,MAAM,EACN,OAAe,EACf,IAAI,GACL,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,WAAW,CAAA;CACzB;kCAOqC,OAAO,CAAC,aAAa,EAAE,CAAC;oBAQpC,OAAO,CAAC,aAAa,EAAE,CAAC;kBAStC,MAAM,GACX,OAAO,CAAC,aAAa,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;EAa1D;AAED,wBAAgB,sBAAsB,CAAC,EACrC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,EACxB,OAAkB,GACnB,GAAE;IACD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5C,IACuB,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAoDhE;AAuBD,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG,KAAK,CAAC,EACjE,EAAE,YAAiB,EAAE,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,UAgBxD"}