@heyo-sh/heyo-cms 0.0.0-stage → 0.1.0

package/dist/auth/oauth.d.ts

@@ -0,0 +1,93 @@
+import type { JsonObject } from "../types/json";
+/**
+ * OAuth 2.0 and OpenID Connect, as plain functions.
+ *
+ * Nothing here touches the database or the configuration: a provider is a
+ * record of endpoints plus a function that turns whatever the provider
+ * returns into the three things the CMS needs — a stable id, an email and a
+ * display name. Adding a provider is therefore a literal, not a subclass.
+ */
+export interface OAuthProfile {
+    /** Stable at the provider. Never the email: emails get reassigned. */
+    id: string;
+    email: string | null;
+    name: string | null;
+    avatarUrl: string | null;
+    /** Everything the provider said, for `oidc().mapRoles`. */
+    claims: JsonObject;
+}
+export interface OAuthTokens {
+    accessToken: string;
+    idToken?: string;
+    tokenType?: string;
+}
+export interface OAuthEndpoints {
+    authorization: string;
+    token: string;
+    userinfo?: string;
+}
+export interface OAuthProvider {
+    id: string;
+    endpoints: OAuthEndpoints;
+    scope: string;
+    /** Proof Key for Code Exchange. Off for GitHub, which does not accept it. */
+    pkce: boolean;
+    profile(tokens: OAuthTokens, fetchImpl: FetchLike): Promise<OAuthProfile>;
+}
+/**
+ * Just the call signature, not `typeof fetch`.
+ *
+ * Runtimes decorate the global with their own extras — Bun adds `preconnect`
+ * — and typing against the global would make a hand-written test double fail
+ * to compile for a reason that has nothing to do with HTTP.
+ */
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * The three providers the plan names.
+ *
+ * Google and Microsoft are OpenID Connect, so the profile comes from the
+ * id_token and needs no second round trip. GitHub is plain OAuth 2 and hides
+ * a verified address behind a separate endpoint when the public profile has
+ * none, which is the common case for a work account.
+ */
+export declare const builtinProviders: Record<string, OAuthProvider>;
+/** The shape every OIDC provider agrees on, including a custom issuer. */
+export declare function oidcProfile(claims: JsonObject): OAuthProfile;
+/**
+ * Reads an id_token without verifying its signature.
+ *
+ * Allowed, and only allowed, because of how it arrives: the authorization code
+ * flow fetches it from the token endpoint over TLS, with the client
+ * authenticating itself — OpenID Connect Core 3.1.3.7 explicitly permits
+ * skipping signature validation on that path. A token that reached us any
+ * other way must never be passed to this function.
+ */
+export declare function decodeIdToken(token: string): JsonObject;
+export declare function discoverOidc(issuer: string, fetchImpl: FetchLike): Promise<OAuthEndpoints>;
+export interface AuthorizeUrlOptions {
+    endpoints: OAuthEndpoints;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    /** The S256 challenge; omitted for providers that reject PKCE. */
+    codeChallenge?: string;
+    extra?: Record<string, string>;
+}
+export declare function buildAuthorizeUrl(options: AuthorizeUrlOptions): string;
+/** The PKCE pair: a verifier to keep, a challenge to publish. */
+export declare function pkcePair(verifier: string): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+export interface ExchangeOptions {
+    endpoints: OAuthEndpoints;
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier?: string;
+    fetchImpl: FetchLike;
+}
+export declare function exchangeCode(options: ExchangeOptions): Promise<OAuthTokens>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2DAA2D;IAC3D,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,cAAc,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3E;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAyE1D,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAQ5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAavD;AAWD,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,cAAc,CAAC,CA8BzB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAetE;AAED,iEAAiE;AACjE,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAElD;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,WAAW,CAAC,CAuCtB"}

package/dist/auth/service.d.ts

@@ -0,0 +1,38 @@
+import type { CmsAuth } from "../types/auth";
+import type { ResolvedCmsConfig } from "../types/config";
+import type { DatabaseAdapter } from "../types/database";
+import type { Tx } from "../types/query";
+import type { BufferedEvent, OutboxEntryMeta } from "../engine/outbox";
+import { type FetchLike } from "./oauth";
+/** The cookie the panel uses. Named here so stage 7 cannot invent a second. */
+export declare const sessionCookieName = "heyo_cms_session";
+/**
+ * API keys announce themselves.
+ *
+ * One `Authorization: Bearer` header carries either a session token or a
+ * machine key, and the prefix is what tells them apart without a database
+ * round trip against both tables.
+ */
+export declare const apiKeyPrefix = "hck_";
+export interface AuthServiceOptions {
+    config: ResolvedCmsConfig;
+    database: () => Promise<DatabaseAdapter>;
+    /** Appends events to the outbox inside the caller's transaction. */
+    emit: (tx: Tx, events: BufferedEvent[], meta: OutboxEntryMeta) => Promise<void>;
+    /** Schedules delivery once the transaction has committed. */
+    deliver: () => void;
+    /** Injectable for tests and for runtimes with a bound fetch. */
+    fetch?: FetchLike;
+}
+/**
+ * Editor authentication and RBAC.
+ *
+ * One implementation, used by the local API today and by the REST routes in
+ * stage 7 — the same reason `cms.api` exists. Everything is a method on this
+ * object rather than a route handler, so a CLI, a seed script and a panel all
+ * get identical behaviour, including the parts that are easy to get wrong:
+ * single-use tokens, hashed secrets, and a second factor that cannot be
+ * skipped by calling a different function.
+ */
+export declare function createAuth(options: AuthServiceOptions): CmsAuth;
+//# sourceMappingURL=service.d.ts.map

package/dist/auth/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/auth/service.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,OAAO,EAYR,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAO,EAAE,EAAS,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAQL,KAAK,SAAS,EAIf,MAAM,SAAS,CAAC;AAUjB,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAoBnC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IACzC,oEAAoE;IACpE,IAAI,EAAE,CACJ,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,eAAe,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,gEAAgE;IAChE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CA0qD/D"}

package/dist/auth/totp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TOTP (RFC 6238), on Web Crypto.
+ *
+ * Six digits, thirty seconds, HMAC-SHA1 — not because SHA-1 is a good hash in
+ * 2026, but because it is what every authenticator app implements, and a
+ * second factor nobody can enrol is not a second factor.
+ */
+/** 160 bits, the size RFC 4226 recommends for the HMAC-SHA1 key. */
+export declare function generateTotpSecret(): string;
+/**
+ * The `otpauth://` URI an authenticator scans.
+ *
+ * The issuer appears twice — as a label prefix and as a parameter — which is
+ * redundant and is also what every app expects.
+ */
+export declare function totpUri(options: {
+    secret: string;
+    account: string;
+    issuer: string;
+}): string;
+export declare function totpCode(secret: string, at?: number): Promise<string>;
+/**
+ * Verifies a code, allowing one step either side.
+ *
+ * The window is for clock drift between the phone and the server, not for
+ * convenience: widening it multiplies the number of codes that are valid at
+ * any moment, which is exactly what the second factor is trying to limit.
+ */
+export declare function verifyTotp(secret: string | null | undefined, code: string, options?: {
+    at?: number;
+    window?: number;
+}): Promise<boolean>;
+export declare function base32Encode(bytes: Uint8Array): string;
+//# sourceMappingURL=totp.d.ts.map

package/dist/auth/totp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.d.ts","sourceRoot":"","sources":["../../src/auth/totp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAUT;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,EAAE,SAAa,GACd,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,OAAO,CAAC,CAmBlB;AA+BD,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAetD"}

package/dist/auth.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@heyo-sh/heyo-cms/auth`.
+ *
+ * `cmsUsers()` and `oidc()` describe who may sign in; the service behind
+ * `cms.auth` does the signing in. Both live here so a configuration file and
+ * a route handler import from the same place.
+ */
+export * from "./auth/index";
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC"}

package/dist/auth.js

@@ -0,0 +1 @@
+import"./index-vxw0a03g.js";import{Re}from"./index-2z1qe5mw.js";import{Dn,kt,Mn,qn,Wo,Xt,fe,en,tn}from"./index-5ngtc7gy.js";import{ke,nn,he,Q,X}from"./index-kbsgt44t.js";import{b}from"./index-cbwwtcm4.js";import{n}from"./index-x72d1hzh.js";function o(e){if(e.methods.length===0)throw new n("admin.auth.methods","at least one sign-in method is required");for(let[s,t]of[["session",e.session?.expiresIn],["invites",e.invites?.expiresIn],["magicLink",e.magicLink?.expiresIn],["passwordReset",e.passwordReset?.expiresIn],["apiKeys",e.apiKeys?.expiresIn]])if(t)b(t,`admin.auth.${s}.expiresIn`);for(let s of e.apiKeys?.scopes??[])if(!Re(s))throw new n("admin.auth.apiKeys.scopes",`"${s}" is not a scope; use "read", "write", "delete", "*" or "collection:action"`);let i=e.firstUser;if(typeof i==="object"){let s=i.roles;if(s!==void 0&&s.length===0)throw new n("admin.auth.firstUser.roles","the first account needs at least one role")}if(i!==void 0&&i!==!1&&!e.methods.includes("password"))throw new n("admin.auth.firstUser",'the first account signs in with a password; add "password" to methods, or set firstUser: false');let r=e.password?.minLength;if(r!==void 0&&r<8)throw new n("admin.auth.password.minLength","must be at least 8");return{kind:"cms-users",...e}}function a(e){if(!/^https?:\/\//.test(e.issuer))throw new n("admin.auth.sso.issuer","must be an HTTP(S) issuer URL");return{kind:"oidc",...e}}export{en as apiKeyPrefix,X as base64url,Dn as builtinProviders,o as cmsUsers,tn as createAuth,kt as decodeIdToken,Mn as generateTotpSecret,ke as hashPassword,Q as hashToken,a as oidc,he as randomToken,fe as sessionCookieName,Wo as totpCode,qn as totpUri,nn as verifyPassword,Xt as verifyTotp};

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8DA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+B1D"}

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import"./index-2z1qe5mw.js";import"./index-vxw0a03g.js";import"./index-ty698y02.js";import"./index-9zqnf6gx.js";import"./index-vq2978e7.js";import"./index-nvgwyykk.js";import"./index-wj8y1xcj.js";import{Zt,$n,jn,In}from"./index-9x1z3b85.js";import{St,Ot,an}from"./index-34s342fz.js";import{Pt,$t,jt,It,Et}from"./index-md79xr6h.js";import"./index-hq05mc1n.js";import"./index-5ngtc7gy.js";import{createRequire as C}from"node:module";var m=C(import.meta.url);import{createReadStream as b,createWriteStream as v}from"node:fs";import{readFile as p,stat as k}from"node:fs/promises";import{isAbsolute as I,resolve as l}from"node:path";import{pathToFileURL as M}from"node:url";import{randomBytes as P}from"node:crypto";var g=`
+  heyo-cms generate [--name <name>]   write a migration for what changed
+  heyo-cms migrate                    apply pending migrations
+  heyo-cms status                     show applied, pending and unplanned changes
+
+  heyo-cms create-admin               create an editor account from a shell
+    --email <address>   required unless HEYO_CMS_ADMIN_EMAIL is set
+    --password <value>  default: generated and printed once
+    --name <name>       display name
+    --roles <a,b>       default: admin
+
+  heyo-cms seed [--file <path>]       run the project's seed module
+
+  heyo-cms export [--out <file>]      write content as NDJSON (default: stdout)
+    --collections <a,b>  default: every collection
+    --globals <a,b>      default: every global
+    --include-trashed    include documents in the trash
+
+  heyo-cms import <file>              read an export back ("-" is stdin)
+    --on-conflict <skip|update|fail>   default: skip
+    --dry-run            parse and report without writing
+
+  heyo-cms telemetry                  print exactly what would be reported
+
+  --config <path>   configuration module (default: ./heyo-cms.config.ts)
+  --dir <path>      migrations directory (default: the one in the config)
+  --env <path>      environment file (default: ./.env, then ./.env.local)
+`;async function _(e){let{command:n,positionals:o,flags:t}=N(e);if(!n||n==="help"||t.has("--help"))return console.log(g),n&&n!=="help"?1:0;await U(t.get("--env"));let s=await j(t.get("--config"));switch(n){case"generate":case"migrate":case"status":return await A(n,s,t);case"create-admin":return await d(n,s,await x(s,t));case"seed":return await d(n,s,await O(s,t));case"export":return await d(n,s,await R(s,t));case"import":return await d(n,s,await W(s,o[1],t));case"telemetry":return await D(s);default:return console.error(`Unknown command: ${n}`),console.log(g),1}}async function A(e,n,o){let t=l(o.get("--dir")??n._config.migrationsDirectory),s=new Zt(t),a=await n.database();if(e==="generate"){let i=await $n({adapter:a,store:s,target:n.schema,plugins:n._config.plugins.flatMap((c)=>(c.migrations??[]).map((u)=>({plugin:c.id,id:u.id,steps:u.steps}))),...o.get("--name")?{name:o.get("--name")}:{}});if(i.created){console.log(`Wrote ${i.file}`);for(let c of i.summary)console.log(`  ${c}`)}for(let c of i.plugins??[])console.log(`Wrote ${c.file} (plugin migration)`);if(!i.created&&(i.plugins??[]).length===0)console.log("No schema changes. Nothing to generate.");return await d(e,n,0)}if(e==="migrate"){let i=await jn({adapter:a,store:s});if(i.applied.length===0)return console.log(`Up to date (${i.alreadyApplied} migration(s) already applied).`),await d(e,n,0);for(let c of i.applied)console.log(`Applied ${c}`);return await d(e,n,0)}let r=await In({adapter:a,store:s,target:n.schema});console.log(`Applied:  ${r.applied.length}`);for(let i of r.pending)console.log(`  pending  ${i}`);for(let i of r.modified)console.log(`  MODIFIED ${i} (applied, then edited)`);if(r.unplanned.length>0)console.log(`  ${r.unplanned.length} change(s) in the configuration have no migration yet; run "heyo-cms generate".`);return r.pending.length>0||r.modified.length>0||r.unplanned.length>0?1:0}async function x(e,n){let o=n.get("--email")??process.env.HEYO_CMS_ADMIN_EMAIL;if(!o)return console.error("An address is required: heyo-cms create-admin --email you@example.com"),1;let t=n.get("--password")??process.env.HEYO_CMS_ADMIN_PASSWORD,s=t??E(),a=(n.get("--roles")??"admin").split(",").map((c)=>c.trim()).filter((c)=>c.length>0),r=await e.auth.users.byEmail(o);if(r)return console.error(`${o} already has an account (${r.status}). Use the panel, or cms.auth.users.setPassword().`),1;let i=await e.auth.users.create({email:o,password:s,roles:a,status:"active",...n.get("--name")?{name:n.get("--name")}:{}});if(await e.drainEvents(),console.log(`Created ${i.email} with role(s) ${i.roles.join(", ")}.`),!t)console.log(`Password: ${s}`),console.log("This is the only time it is shown.");return console.log(`Sign in at ${e._config.basePath}${e._config.admin.path}.`),0}function E(){return P(24).toString("base64url")}var S=["heyo-cms.seed.ts","heyo-cms.seed.js","seed.ts","src/heyo-cms.seed.ts"];async function O(e,n){let o=n.get("--file")?l(n.get("--file")):await y(S,"seed module"),t=await h(o),s=t.seed??t.default;if(typeof s!=="function")return console.error(`${o} does not export a seed. Add \`export async function seed(cms) { ... }\`.`),1;return await s(e),await e.drainEvents(),console.log(`Seeded from ${o}.`),0}async function R(e,n){let o=n.get("--out"),t=o?F(l(o)):Y(),s=0,a=0;try{for await(let r of It(e,{...f(n,"--collections","collections"),...f(n,"--globals","globals"),...n.has("--include-trashed")?{includeTrashed:!0}:{}})){if(r.kind==="document")s+=1;if(r.kind==="global")a+=1;await t.line(jt(r))}}finally{await t.close()}return console.error(`Exported ${s} document(s) and ${a} global(s).`),0}async function W(e,n,o){if(!n)return console.error('A file is required: heyo-cms import content.ndjson (or "-").'),1;let t=o.get("--on-conflict")??"skip";if(!["skip","update","fail"].includes(t))return console.error(`--on-conflict takes skip, update or fail; got ${t}.`),1;let s={onConflict:t,...o.has("--dry-run")?{dryRun:!0}:{}},a=n==="-"?H():q(l(n)),r=await Et(e,Pt($t(a)),s),i=s.dryRun?"Would import":"Imported";if(console.log(`${i} ${r.documents.created} new and ${r.documents.updated} updated document(s), ${r.globals.updated} global(s).`),r.documents.skipped>0)console.log(`Skipped ${r.documents.skipped} document(s).`);for(let c of r.errors)console.error(`  ${c}`);return r.errors.length>0?1:0}async function D(e){let n=St(e._config.telemetry),o=Ot("telemetry",e,await w());return console.log(n.enabled?"Telemetry: on":"Telemetry: off"),console.log(`  ${n.reason}`),console.log(""),console.log("  What a command would send, in full:"),console.log(""),console.log(JSON.stringify(o,null,2)),console.log(""),console.log("  Turn it off with any of:"),console.log("    HEYO_TELEMETRY_DISABLED=1"),console.log("    DO_NOT_TRACK=1"),console.log("    telemetry: { enabled: false } in heyo-cms.config.ts"),console.log(""),0}async function d(e,n,o){try{await an({event:e,cms:n,version:await w(),...n._config.telemetry?{config:n._config.telemetry}:{}})}catch{}return o}function N(e){let n=new Map,o=[];for(let t=0;t<e.length;t+=1){let s=e[t];if(!s.startsWith("--")){o.push(s);continue}let a=e[t+1];if(a!==void 0&&!a.startsWith("--"))n.set(s,a),t+=1;else n.set(s,"true")}return{command:o[0],positionals:o,flags:n}}function f(e,n,o){let t=e.get(n);if(!t||t==="true")return{};return{[o]:t.split(",").map((s)=>s.trim()).filter((s)=>s.length>0)}}var T=["heyo-cms.config.ts","heyo-cms.config.js","heyo-cms.config.mjs","src/heyo-cms.config.ts","app/heyo-cms.config.ts"];async function j(e){let n=e?l(e):await y(T,"configuration"),o=await h(n),t=o.cms??o.default;if(!L(t))throw Error(`${n} does not export a CMS. Add \`export const cms = heyoCms({ ... })\`.`);return t}async function h(e){return await(I(e)?import(M(e).href):import(e))}async function y(e,n){for(let o of e){let t=l(o);try{return await k(t),t}catch{}}throw Error(`No ${n} found. Looked for ${e.join(", ")}. Use --config or --file.`)}function L(e){return typeof e==="object"&&e!==null&&"_config"in e&&"schema"in e&&typeof e.database==="function"}async function U(e){let n=e?[l(e)]:[l(".env"),l(".env.local")];for(let o of n){let t;try{t=await p(o,"utf8")}catch{if(e)throw Error(`No environment file at ${o}.`);continue}for(let s of t.split(`
+`)){let a=/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(s);if(!a)continue;let[,r,i]=a;if(process.env[r]!==void 0)continue;let c=i.trim(),u=/^(["'])([\s\S]*)\1$/.exec(c);process.env[r]=u?u[2]:c.split(" #")[0].trim()}}}async function w(){try{let e=await p(new URL("../package.json",import.meta.url),"utf8");return JSON.parse(e).version??"0.0.0"}catch{return"0.0.0"}}function F(e){let n=v(e,{encoding:"utf8"});return{line:(o)=>new Promise((t,s)=>{n.write(o,(a)=>a?s(a):t())}),close:()=>new Promise((o)=>n.end(()=>o()))}}function Y(){return{line:(e)=>new Promise((n,o)=>{process.stdout.write(e,(t)=>t?o(t):n())}),close:async()=>{}}}async function*q(e){let n=b(e,{encoding:"utf8"});for await(let o of n)yield o}async function*H(){process.stdin.setEncoding("utf8");for await(let e of process.stdin)yield e}if(m.main==m.module)_(process.argv.slice(2)).then((e)=>{process.exitCode=e}).catch((e)=>{console.error(e instanceof Error?e.message:String(e)),process.exitCode=1});export{_ as main};

package/dist/client/index.d.ts

@@ -0,0 +1,51 @@
+import type { CmsPlugin } from "../types/plugin";
+import type { CmsClient, PluginExtensions } from "./types";
+/**
+ * The typed client.
+ *
+ * The public entry point picks up the project's registered CMS type, so
+ * `heyoCmsClient()` is typed without importing server configuration into the
+ * browser bundle. `heyoCmsClient<typeof cms>()` remains available for a
+ * project with more than one CMS. The methods
+ * mirror `cms.api` exactly, because the routes they call are three lines
+ * around `cms.api`: code written against the local API moves to the client by
+ * changing the object it is called on.
+ *
+ * What it is not: an ORM, a cache or a state manager. It is `fetch` with the
+ * URL building, the error shape and the 204 convention taken care of, and it
+ * is tiny on purpose — this ships to browsers.
+ */
+export interface CmsClientOptions<TPlugins extends readonly CmsPlugin<unknown>[] = []> {
+    /**
+     * Where the handler is mounted.
+     *
+     * Defaults to the same-origin `/api/heyo-cms` mount in a browser. Set this
+     * for a custom mount or a CMS on another origin, e.g.
+     * `https://cms.acme.dev/api/heyo-cms`.
+     */
+    baseUrl?: string;
+    /**
+     * A session token or an API key.
+     *
+     * A function is resolved per request, which is what makes a rotating key or
+     * a token read out of a cookie store work without rebuilding the client.
+     * Omit it in a browser: the session cookie is sent automatically.
+     */
+    token?: string | (() => string | null | undefined | Promise<string | null | undefined>);
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Injectable so a test, a Worker or a framework's own `fetch` can be used. */
+    fetch?: typeof fetch;
+    /** Defaults to `same-origin`, which is what a cookie session needs. */
+    credentials?: RequestCredentials;
+    /**
+     * The plugins whose client extensions should be installed.
+     *
+     * Passed rather than discovered: the configuration lives on the server and
+     * the client is a browser bundle, so the only way the extension types can
+     * reach it is through this list.
+     */
+    plugins?: TPlugins;
+}
+export declare function heyoCmsClient<TCms = import("../types/instance").CmsInstance, const TPlugins extends readonly CmsPlugin<unknown>[] = []>(options?: CmsClientOptions<TPlugins>): CmsClient<TCms> & PluginExtensions<TPlugins>;
+export type * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EASV,SAAS,EACT,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,gBAAgB,CAC/B,QAAQ,SAAS,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;IAEnD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,uEAAuE;IACvE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAgB,aAAa,CAC3B,IAAI,GAAG,OAAO,mBAAmB,EAAE,WAAW,EAC9C,KAAK,CAAC,QAAQ,SAAS,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,EAEzD,OAAO,GAAE,gBAAgB,CAAC,QAAQ,CAAM,GACvC,SAAS,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAmO9C;AA+RD,mBAAmB,SAAS,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,340 @@
+import type { CollectionsConfig, GlobalsConfig, InferDocument } from "../types/config";
+import type { CmsInstance } from "../types/instance";
+import type { ActivityListArgs, ActivityPage } from "../types/activity";
+import type { ApiKeyRecord, CmsUser, IssuedApiKey, RoleRecord, SignInResult } from "../types/auth";
+import type { FindResult } from "../types/api";
+import type { JsonObject } from "../types/json";
+import type { LocaleRecord } from "../types/locales";
+import type { MediaDocument, MediaListResult, MediaUsage } from "../types/media";
+import type { CmsPlugin } from "../types/plugin";
+import type { OrderBy, Where } from "../types/query";
+import type { TrashPage } from "../types/trash";
+import type { JobFailure, JobRunReport } from "../types/jobs";
+/**
+ * The typed client's argument types.
+ *
+ * Shaped after the local API on purpose: `client.posts.find({ where: eq(...) })`
+ * and `cms.api.posts.find({ where: eq(...) })` take the same object, because
+ * the second is what the first ends up calling (section 10). The filter
+ * helpers from `@heyo-sh/heyo-cms/query` therefore work on both sides of the
+ * network, and there is one query language in the product rather than one per
+ * transport.
+ */
+export interface ClientLocaleArgs {
+    locale?: string;
+    fallbackLocale?: string | false;
+}
+export interface ClientReadArgs extends ClientLocaleArgs {
+    depth?: number;
+    includeTrashed?: boolean;
+    /** Per-call headers, e.g. a one-off `authorization`. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface ClientFindArgs extends ClientReadArgs {
+    where?: Where;
+    orderBy?: OrderBy[];
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    count?: boolean;
+}
+export type ClientInput<TDoc> = Partial<Omit<TDoc, "id" | "createdAt" | "updatedAt" | "updatedBy" | "deletedAt" | "purgeAfter" | "scheduledAt" | "scheduledPatch" | "_fallback">>;
+export interface ClientCreateArgs<TDoc> extends ClientReadArgs {
+    data: ClientInput<TDoc>;
+}
+export interface ClientUpdateArgs<TDoc> extends ClientReadArgs {
+    id: string;
+    data: ClientInput<TDoc>;
+}
+export interface ClientDeleteArgs extends ClientReadArgs {
+    id: string;
+    /** Skips the trash. Governed by the `purge` permission. */
+    permanent?: boolean;
+}
+export interface ClientScheduleArgs<TDoc> extends ClientReadArgs {
+    id: string;
+    at: Date | string;
+    data: ClientInput<TDoc>;
+}
+/**
+ * One collection, over HTTP.
+ *
+ * A write answers `null` when a `before` hook stopped it — the 204 the route
+ * sends — so the client's return types match the local API's exactly and code
+ * can move between them without a change.
+ */
+export interface ClientCollection<TDoc> {
+    find(args?: ClientFindArgs): Promise<FindResult<TDoc>>;
+    findById(id: string, args?: ClientReadArgs): Promise<TDoc | null>;
+    create(args: ClientCreateArgs<TDoc>): Promise<TDoc | null>;
+    update(args: ClientUpdateArgs<TDoc>): Promise<TDoc | null>;
+    delete(args: ClientDeleteArgs): Promise<TDoc | null>;
+    restore(args: {
+        id: string;
+    } & ClientReadArgs): Promise<TDoc | null>;
+    schedule(args: ClientScheduleArgs<TDoc>): Promise<TDoc | null>;
+    unschedule(args: {
+        id: string;
+    } & ClientReadArgs): Promise<TDoc | null>;
+}
+export interface ClientGlobal<TDoc> {
+    get(args?: ClientReadArgs): Promise<TDoc>;
+    update(args: {
+        data: ClientInput<TDoc>;
+    } & ClientReadArgs): Promise<TDoc | null>;
+    schedule(args: {
+        at: Date | string;
+        data: ClientInput<TDoc>;
+    } & ClientReadArgs): Promise<TDoc | null>;
+    unschedule(args?: ClientReadArgs): Promise<TDoc | null>;
+}
+export interface ClientUploadArgs {
+    file: Blob | Uint8Array | ArrayBuffer;
+    filename?: string;
+    contentType?: string;
+    alt?: string;
+    locale?: string;
+    metadata?: JsonObject;
+    signal?: AbortSignal;
+}
+export interface ClientMedia {
+    upload(args: ClientUploadArgs | File): Promise<MediaDocument>;
+    list(args?: {
+        status?: MediaDocument["status"];
+        mimeType?: string;
+        search?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<MediaListResult>;
+    get(id: string): Promise<MediaDocument | null>;
+    update(args: {
+        id: string;
+        filename?: string;
+        alt?: string | Record<string, string>;
+        locale?: string;
+        focalPoint?: {
+            x: number;
+            y: number;
+        } | null;
+        crop?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | null;
+        metadata?: JsonObject;
+    }): Promise<MediaDocument>;
+    delete(args: {
+        id: string;
+        force?: boolean;
+    }): Promise<MediaDocument>;
+    keep(args: {
+        id: string;
+    }): Promise<MediaDocument>;
+    usages(id: string): Promise<MediaUsage[]>;
+    /**
+     * The URL of a size, built rather than fetched.
+     *
+     * A string, not a request: this is what goes into an `<img src>`, and a
+     * client that had to await the bytes to produce a URL would make rendering
+     * a list of thumbnails a waterfall.
+     */
+    url(id: string, variant?: string): string;
+}
+export interface ClientAuth {
+    signIn(args: {
+        email: string;
+        password: string;
+    }): Promise<SignInResult>;
+    /**
+     * Creates the first account on a CMS that has none, and signs it in.
+     *
+     * Answers 409 once any account exists; `GET /panel` reports whether it is
+     * still open as `auth.setupRequired`.
+     */
+    claimFirstAccount(args: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<SignInResult>;
+    signOut(): Promise<void>;
+    session(): Promise<{
+        actor: unknown | null;
+        user: CmsUser | null;
+    }>;
+    magicLink(args: {
+        email: string;
+    }): Promise<{
+        status: string;
+    }>;
+    verifyMagicLink(args: {
+        token: string;
+    }): Promise<SignInResult>;
+    forgotPassword(args: {
+        email: string;
+    }): Promise<{
+        status: string;
+    }>;
+    resetPassword(args: {
+        token: string;
+        password: string;
+    }): Promise<{
+        user: CmsUser;
+    }>;
+    acceptInvite(args: {
+        token: string;
+        password?: string;
+        name?: string;
+    }): Promise<SignInResult>;
+    verifyTwoFactor(args: {
+        challenge: string;
+        code: string;
+    }): Promise<SignInResult>;
+    beginTwoFactor(): Promise<{
+        secret: string;
+        uri: string;
+    }>;
+    enableTwoFactor(args: {
+        code: string;
+    }): Promise<{
+        user: CmsUser;
+    }>;
+    disableTwoFactor(): Promise<{
+        user: CmsUser;
+    }>;
+    apiKeys: {
+        list(): Promise<ApiKeyRecord[]>;
+        create(args: {
+            name: string;
+            scopes?: string[];
+        }): Promise<IssuedApiKey>;
+        revoke(id: string): Promise<void>;
+    };
+    /** The URL to send a browser to for an OAuth or SSO sign-in. */
+    oauthUrl(provider: string, redirectTo?: string): string;
+}
+export interface ClientUsers {
+    list(args?: {
+        status?: CmsUser["status"];
+        search?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        users: CmsUser[];
+        totalUsers: number;
+    }>;
+    get(id: string): Promise<CmsUser | null>;
+    update(id: string, args: {
+        name?: string | null;
+        roles?: string[];
+        status?: CmsUser["status"];
+        locale?: string | null;
+    }): Promise<CmsUser>;
+    invite(args: {
+        email: string;
+        name?: string;
+        roles?: string[];
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+        user: CmsUser;
+    }>;
+    remove(id: string): Promise<void>;
+}
+export interface ClientRoles {
+    list(): Promise<RoleRecord[]>;
+    create(args: {
+        name: string;
+        permissions: string[];
+        label?: string;
+    }): Promise<RoleRecord>;
+    update(name: string, args: {
+        permissions?: string[];
+        label?: string | null;
+    }): Promise<RoleRecord>;
+    remove(name: string): Promise<void>;
+}
+export interface ClientTrash {
+    list(args?: {
+        collection?: string;
+        limit?: number;
+        cursor?: string;
+        locale?: string;
+    }): Promise<TrashPage>;
+    restore(args: {
+        collection: string;
+        id: string;
+    }): Promise<JsonObject>;
+    purge(args: {
+        collection: string;
+        id: string;
+    }): Promise<JsonObject>;
+}
+/**
+ * The configured languages.
+ *
+ * Read-only, because `i18n.locales` is code: a client that could add one
+ * would be editing a file it cannot see.
+ */
+export interface ClientLocales {
+    list(): Promise<{
+        locales: LocaleRecord[];
+        defaultLocale: string;
+    }>;
+}
+export interface ClientJobs {
+    run(args?: {
+        limit?: number;
+        only?: string[];
+    }): Promise<JobRunReport>;
+    failures(args?: {
+        type?: string;
+        limit?: number;
+    }): Promise<JobFailure[]>;
+}
+/** The escape hatch, and what a plugin's client extension is built on. */
+export interface ClientRequest {
+    (path: string, init?: RequestInit & {
+        query?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+export interface ClientCore {
+    baseUrl: string;
+    request: ClientRequest;
+    media: ClientMedia;
+    auth: ClientAuth;
+    users: ClientUsers;
+    roles: ClientRoles;
+    trash: ClientTrash;
+    locales: ClientLocales;
+    activity: {
+        list(args?: ActivityListArgs): Promise<ActivityPage>;
+    };
+    jobs: ClientJobs;
+    openapi(): Promise<JsonObject>;
+}
+/** Collections become top-level properties, as in `client.posts.find()`. */
+export type ClientCollections<TCollections extends CollectionsConfig> = {
+    [K in keyof TCollections]: ClientCollection<InferDocument<TCollections[K]>>;
+};
+export type ClientGlobals<TGlobals extends GlobalsConfig> = {
+    [K in keyof TGlobals]: ClientGlobal<InferDocument<TGlobals[K]>>;
+};
+/**
+ * The client for one configuration.
+ *
+ * `globals` is a property rather than being flattened next to the collections
+ * because a global and a collection can share a name in different registries
+ * and a flat namespace would make that a silent overwrite.
+ */
+export type CmsClient<TCms> = TCms extends CmsInstance<infer TCollections, infer TGlobals> ? ClientCore & ClientCollections<TCollections> & {
+    globals: ClientGlobals<TGlobals>;
+} : never;
+/** Turns a plugin tuple into the intersection of what their clients add. */
+export type PluginExtensions<TPlugins extends readonly CmsPlugin<unknown>[]> = UnionToIntersection<{
+    [K in keyof TPlugins]: TPlugins[K] extends CmsPlugin<infer Ext> ? Ext : never;
+}[number]>;
+type UnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+export {};
+//# sourceMappingURL=types.d.ts.map