@backmatter/core 0.0.6 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/config.ts

@@ -15,9 +15,9 @@ export type BackmatterDirs = {
 };
 
 export type BackmatterConfig = {
-  /** Required only when talking to the BACKMATTER API. Env: BACKMATTER_WORKSPACE_ID. */
+  /** Workspace id (`ws_…`), not the dashboard slug. Config first; env BACKMATTER_WORKSPACE_ID overrides gap. */
   workspaceId?: string;
-  /** Env: BACKMATTER_API_URL. When set with workspaceId, published docs load from the API. */
+  /** CMS API origin. Config / BACKMATTER_API_URL, else cloud API on a deployed host when workspaceId is set. */
   apiUrl?: string;
   /** Env: BACKMATTER_CONTENT_TOKEN. Required only to read non-default branches. */
   contentToken?: string;
@@ -53,6 +53,7 @@ export const DEFAULT_DIRS: Required<BackmatterDirs> = {
   layouts: "layouts",
 };
 export const DEFAULT_LOCALE = "en";
+export const CLOUD_API_URL = "https://api.backmatter.app";
 
 function withHttps(url: string): string {
   if (url.startsWith("http://") || url.startsWith("https://")) return url;
@@ -63,6 +64,46 @@ function stripTrailingSlash(url: string): string {
   return url.endsWith("/") ? url.slice(0, -1) : url;
 }
 
+function envOf(): Record<string, string | undefined> {
+  return typeof process === "undefined" ? {} : process.env;
+}
+
+/** Vercel, Netlify, Cloudflare Pages, Railway, or NODE_ENV=production. */
+export function isDeployedHost(env: Record<string, string | undefined>): boolean {
+  return Boolean(
+    env.VERCEL ||
+      env.NETLIFY ||
+      env.CF_PAGES ||
+      env.RAILWAY_ENVIRONMENT ||
+      env.NODE_ENV === "production",
+  );
+}
+
+/** DevBar /me origin: explicit, else env, else cloud API on a deployed host. */
+export function resolveDevBarApiUrl(
+  explicit: string | undefined,
+  env: Record<string, string | undefined> = envOf(),
+): string {
+  const fromProp = explicit?.trim();
+  if (fromProp) return stripTrailingSlash(fromProp);
+  const fromEnv = env.BACKMATTER_API_URL?.trim();
+  if (fromEnv) return stripTrailingSlash(fromEnv);
+  if (isDeployedHost(env)) return CLOUD_API_URL;
+  return "";
+}
+
+function detectApiUrl(
+  config: BackmatterConfig,
+  env: Record<string, string | undefined>,
+  workspaceId: string | undefined,
+): string | undefined {
+  const explicit = config.apiUrl !== undefined ? config.apiUrl : env.BACKMATTER_API_URL;
+  const trimmed = explicit?.trim();
+  if (trimmed) return stripTrailingSlash(trimmed);
+  if (workspaceId && isDeployedHost(env)) return CLOUD_API_URL;
+  return undefined;
+}
+
 /** Public origin of the host that should receive `content.committed`. */
 export function detectSiteUrl(
   config: { siteUrl?: string } = {},
@@ -90,10 +131,6 @@ export function defineConfig(config: BackmatterConfig): BackmatterConfig {
   return config;
 }
 
-function envOf(): Record<string, string | undefined> {
-  return typeof process === "undefined" ? {} : process.env;
-}
-
 /** Explicit config wins; env vars fill the gaps; folder defaults last. */
 export function resolveConfig(
   config: BackmatterConfig = {},
@@ -104,9 +141,10 @@ export function resolveConfig(
     const fromEnv = env[key]?.trim();
     return fromEnv ? fromEnv : undefined;
   };
+  const workspaceId = pick(config.workspaceId, "BACKMATTER_WORKSPACE_ID");
   return {
-    workspaceId: pick(config.workspaceId, "BACKMATTER_WORKSPACE_ID"),
-    apiUrl: pick(config.apiUrl, "BACKMATTER_API_URL"),
+    workspaceId,
+    apiUrl: detectApiUrl(config, env, workspaceId),
     contentToken: pick(config.contentToken, "BACKMATTER_CONTENT_TOKEN"),
     previewToken: pick(config.previewToken, "BACKMATTER_PREVIEW_TOKEN"),
     hostToken: pick(config.hostToken, "BACKMATTER_HOST_TOKEN"),

package/src/index.ts

@@ -42,7 +42,16 @@ export type { DocFormat } from "./doc-format";
 export { modelFormat, parseDoc, serializeDoc } from "./doc-format";
 
 export type { BackmatterConfig, BackmatterDirs, ResolvedConfig } from "./config";
-export { defineConfig, resolveConfig, detectSiteUrl, DEFAULT_DIRS, DEFAULT_LOCALE } from "./config";
+export {
+  defineConfig,
+  resolveConfig,
+  detectSiteUrl,
+  isDeployedHost,
+  resolveDevBarApiUrl,
+  DEFAULT_DIRS,
+  DEFAULT_LOCALE,
+  CLOUD_API_URL,
+} from "./config";
 
 export type { RouteMatch, RouteModel, MatchRouteOptions } from "./routes";
 export {
@@ -106,6 +115,8 @@ export {
   PREVIEW_COOKIE,
   PREVIEW_ENABLE_PATH,
   PREVIEW_QUERY,
+  PREVIEW_CHECKOUT_QUERY,
+  previewLocationWithCheckout,
   isSafeRedirectPath,
   mintPreviewTicket,
   previewMiddlewareDecision,

package/src/node/cli.ts

@@ -249,8 +249,10 @@ import { defineConfig } from "${from}";
 // General settings only. Models live in models/*.ts, composer blocks in
 // blocks/*.tsx, MDX tags in mdx/*.tsx, and content in
 // content/{locale}/{type}/{slug}.{mdx,json} — all discovered automatically.
-// workspaceId / apiUrl / tokens fall back to BACKMATTER_* env vars when omitted.
+// Set workspaceId from General settings (not an env var).
+// API URL defaults to https://api.backmatter.app in production; tokens stay env.
 export default defineConfig({
+  // workspaceId: "ws_…",
   defaultLocale: "en",
 });
 `;

package/src/preview-session.ts

@@ -3,6 +3,7 @@ import { signPayload, verifyPayload } from "./signed-token";
 
 export const PREVIEW_COOKIE = "backmatter_preview";
 export const PREVIEW_QUERY = "backmatter_preview";
+export const PREVIEW_CHECKOUT_QUERY = "backmatter_checkout";
 export const PREVIEW_ENABLE_PATH = "/api/backmatter/preview";
 export const PREVIEW_TICKET_TTL_MS = 10 * 60 * 1000;
 export const PREVIEW_COOKIE_TTL_MS = 12 * 60 * 60 * 1000;
@@ -80,6 +81,16 @@ export async function readPreviewTicket(secret: string, token: string): Promise<
   return asTicket(await verifyPayload(secret, token));
 }
 
+export function previewLocationWithCheckout(
+  origin: string,
+  redirect: string,
+  checkout: string,
+): string {
+  const location = new URL(redirect, origin);
+  location.searchParams.set(PREVIEW_CHECKOUT_QUERY, checkout);
+  return location.toString();
+}
+
 export async function writePreviewCookie(
   secret: string,
   input: PreviewCheckout & { exp: number },
@@ -124,7 +135,7 @@ export function previewMiddlewareDecision(url: URL, draftEnabled: boolean): Prev
   if (ticket) {
     return { type: "redirect", location: `${PREVIEW_ENABLE_PATH}?ticket=${encodeURIComponent(ticket)}` };
   }
-  if (draftEnabled) {
+  if (draftEnabled || url.searchParams.get(PREVIEW_CHECKOUT_QUERY)?.trim()) {
     return { type: "headers", headers: { ...PREVIEW_CACHE_HEADERS } };
   }
   return { type: "next" };