@pylonsync/functions 0.5.5 → 0.5.6

package/dist/index.d.ts

@@ -26,4 +26,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, } from "./types";

package/dist/types.d.ts

@@ -775,6 +775,66 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     signal?: AbortSignal;
 }
 /** Context for action handlers (external I/O, non-transactional). */
+/** One DNS record a tenant must set (name + value), as returned by the
+ *  registrar/CDN. Used for the CNAME target's DCV + ownership TXT records. */
+export interface TenantDomainDns {
+    name: string;
+    value: string;
+}
+/** The result of attaching / polling a tenant (platform) custom domain —
+ *  everything your app shows its end-customer to complete DNS setup. */
+export interface TenantDomainResult {
+    hostname: string;
+    /** "provisioning" until the cert is active, then "ready". */
+    status: string;
+    /** Whether the hostname + TLS certificate are both active. */
+    active?: boolean;
+    /** The single CNAME the customer points their hostname at. */
+    cnameTarget: string;
+    /** TXT record proving domain ownership before DNS cutover (or null). */
+    ownership: TenantDomainDns | null;
+    /** TXT records that issue the DV certificate. */
+    dcv: TenantDomainDns[];
+    /** Human-readable provisioning errors, empty when healthy. */
+    errors: string[];
+}
+/**
+ * Platform domains: attach / register / detach custom domains for your app's
+ * OWN end-customers, so each tenant can reach your app on their own hostname.
+ *
+ * Cloud-only — proxies to the Pylon Cloud control plane (which holds the
+ * Cloudflare/registrar credentials the app never sees). On a self-hosted Pylon
+ * every method throws a typed `DOMAINS_NOT_CONFIGURED` error.
+ *
+ * A newly attached hostname is trusted by the app's CORS / WebSocket / SSR
+ * gates automatically (the runtime refreshes the trusted-host set from the
+ * control plane) — no redeploy per tenant.
+ *
+ * @example
+ * ```ts
+ * // In an action, when your customer adds their domain:
+ * const d = await ctx.domains.add("app.customer.com");
+ * // Show them: CNAME app.customer.com -> d.cnameTarget, plus d.dcv TXT records.
+ * // Later, poll:
+ * const s = await ctx.domains.status("app.customer.com"); // s.active === true
+ * ```
+ */
+export interface Domains {
+    /** Attach a custom domain for one of your end-customers. Returns the DNS the
+     *  customer must set (the CNAME target + ownership/DCV TXT records). */
+    add(hostname: string): Promise<TenantDomainResult>;
+    /** Poll a tenant domain's verification + certificate status. */
+    status(hostname: string): Promise<TenantDomainResult>;
+    /** Detach a tenant domain (deletes the hostname + frees the slot). */
+    remove(hostname: string): Promise<{
+        hostname: string;
+        removed: boolean;
+    }>;
+    /** The hostnames currently ready (trusted) for this app — owner + tenant. */
+    list(): Promise<{
+        hosts: string[];
+    }>;
+}
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
     auth: AuthInfo<R>;
     stream: Stream;
@@ -789,6 +849,9 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Durable workflows: start / deliver events — see {@link Workflows}. */
     workflows: Workflows;
+    /** Attach / register custom domains for your app's OWN end-customers
+     *  (platform domains) — see {@link Domains}. Cloud-only. */
+    domains: Domains;
     /** Environment variables / secrets. */
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -90,4 +90,9 @@ export type {
   LlmCompleteResponse,
   LlmStreamEvent,
   Rooms,
+  // Platform domains — app authors name these when handling ctx.domains
+  // results (the DNS the end-customer must set).
+  Domains,
+  TenantDomainResult,
+  TenantDomainDns,
 } from "./types";

package/src/runtime.ts

@@ -31,6 +31,8 @@ import type {
   Rooms,
   Workflows,
   Connections,
+  Domains,
+  TenantDomainResult,
   QueryCtx,
   MutationCtx,
   ActionCtx,
@@ -1056,6 +1058,70 @@ function buildConnections(callId: string): Connections {
   };
 }
 
+/**
+ * `ctx.domains` — platform (tenant) custom domains. Pure TS: proxies to the
+ * Pylon Cloud control plane over HTTP, authed by the machine's own
+ * `PYLON_DOMAINS_TOKEN` (a plain env var stamped at deploy — not a shared
+ * credential, so no Rust-side transport hook like ctx.email needs). Fails LOUD
+ * with `DOMAINS_NOT_CONFIGURED` when the cloud env is absent (self-host), rather
+ * than silently no-opping — a call that looks like it attached a domain but
+ * didn't would be a worse footgun.
+ */
+function buildDomains(): Domains {
+  const cloudUrl = (process.env.PYLON_CLOUD_URL || "").replace(/\/+$/, "");
+  const token = process.env.PYLON_DOMAINS_TOKEN || "";
+
+  async function call<T>(
+    endpoint: string,
+    body: Record<string, unknown>,
+  ): Promise<T> {
+    if (!cloudUrl || !token) {
+      const e = new Error(
+        "custom domains require Pylon Cloud (PYLON_CLOUD_URL / PYLON_DOMAINS_TOKEN are not set on this machine)",
+      );
+      (e as any).code = "DOMAINS_NOT_CONFIGURED";
+      throw e;
+    }
+    const res = await fetch(`${cloudUrl}/api/fn/${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json: any = {};
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = {};
+    }
+    // /api/fn returns the handler's raw value on 200, or
+    // {error:{code,message}} on failure (crates/router json_error).
+    if (!res.ok || json?.error) {
+      const err = new Error(
+        json?.error?.message || `platform-domains ${endpoint} failed (${res.status})`,
+      );
+      (err as any).code = json?.error?.code || "DOMAINS_REQUEST_FAILED";
+      throw err;
+    }
+    return json as T;
+  }
+
+  return {
+    add: (hostname: string) =>
+      call<TenantDomainResult>("provisionTenantDomain", { hostname }),
+    status: (hostname: string) =>
+      call<TenantDomainResult>("getTenantDomainStatus", { hostname }),
+    remove: (hostname: string) =>
+      call<{ hostname: string; removed: boolean }>("removeTenantDomain", {
+        hostname,
+      }),
+    list: () => call<{ hosts: string[] }>("listProjectTrustedHosts", {}),
+  };
+}
+
 function buildActionCtx(
   callId: string,
   auth: AuthInfo,
@@ -1089,6 +1155,7 @@ function buildActionCtx(
     rooms,
     connections,
     workflows: buildWorkflows(callId),
+    domains: buildDomains(),
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
       return rpc(callId, {

package/src/types.ts

@@ -873,6 +873,64 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
 }
 
 /** Context for action handlers (external I/O, non-transactional). */
+/** One DNS record a tenant must set (name + value), as returned by the
+ *  registrar/CDN. Used for the CNAME target's DCV + ownership TXT records. */
+export interface TenantDomainDns {
+  name: string;
+  value: string;
+}
+
+/** The result of attaching / polling a tenant (platform) custom domain —
+ *  everything your app shows its end-customer to complete DNS setup. */
+export interface TenantDomainResult {
+  hostname: string;
+  /** "provisioning" until the cert is active, then "ready". */
+  status: string;
+  /** Whether the hostname + TLS certificate are both active. */
+  active?: boolean;
+  /** The single CNAME the customer points their hostname at. */
+  cnameTarget: string;
+  /** TXT record proving domain ownership before DNS cutover (or null). */
+  ownership: TenantDomainDns | null;
+  /** TXT records that issue the DV certificate. */
+  dcv: TenantDomainDns[];
+  /** Human-readable provisioning errors, empty when healthy. */
+  errors: string[];
+}
+
+/**
+ * Platform domains: attach / register / detach custom domains for your app's
+ * OWN end-customers, so each tenant can reach your app on their own hostname.
+ *
+ * Cloud-only — proxies to the Pylon Cloud control plane (which holds the
+ * Cloudflare/registrar credentials the app never sees). On a self-hosted Pylon
+ * every method throws a typed `DOMAINS_NOT_CONFIGURED` error.
+ *
+ * A newly attached hostname is trusted by the app's CORS / WebSocket / SSR
+ * gates automatically (the runtime refreshes the trusted-host set from the
+ * control plane) — no redeploy per tenant.
+ *
+ * @example
+ * ```ts
+ * // In an action, when your customer adds their domain:
+ * const d = await ctx.domains.add("app.customer.com");
+ * // Show them: CNAME app.customer.com -> d.cnameTarget, plus d.dcv TXT records.
+ * // Later, poll:
+ * const s = await ctx.domains.status("app.customer.com"); // s.active === true
+ * ```
+ */
+export interface Domains {
+  /** Attach a custom domain for one of your end-customers. Returns the DNS the
+   *  customer must set (the CNAME target + ownership/DCV TXT records). */
+  add(hostname: string): Promise<TenantDomainResult>;
+  /** Poll a tenant domain's verification + certificate status. */
+  status(hostname: string): Promise<TenantDomainResult>;
+  /** Detach a tenant domain (deletes the hostname + frees the slot). */
+  remove(hostname: string): Promise<{ hostname: string; removed: boolean }>;
+  /** The hostnames currently ready (trusted) for this app — owner + tenant. */
+  list(): Promise<{ hosts: string[] }>;
+}
+
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
   auth: AuthInfo<R>;
   stream: Stream;
@@ -887,6 +945,9 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Durable workflows: start / deliver events — see {@link Workflows}. */
   workflows: Workflows;
+  /** Attach / register custom domains for your app's OWN end-customers
+   *  (platform domains) — see {@link Domains}. Cloud-only. */
+  domains: Domains;
   /** Environment variables / secrets. */
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */