@pylonsync/functions 0.5.5 → 0.5.7

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, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/types.d.ts

@@ -775,6 +775,140 @@ 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
+ * ```
+ */
+/** One domain-availability / pricing result from a search. */
+export interface DomainAvailability {
+    domainName: string;
+    sld: string;
+    tld: string;
+    purchasable: boolean;
+    premium?: boolean;
+    /** First-term price (USD), when purchasable. */
+    purchasePrice?: number;
+    renewalPrice?: number;
+    purchaseType?: string;
+    /** Why it isn't purchasable, when unavailable. */
+    reason?: string | null;
+}
+/** A registrant/admin/tech/billing contact for a domain registration. */
+export interface DomainContact {
+    firstName: string;
+    lastName: string;
+    companyName?: string;
+    address1: string;
+    address2?: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+    email: string;
+    phone: string;
+    fax?: string;
+}
+/** Options for {@link Domains.register}. `purchasePrice` is a price ceiling —
+ *  registration is refused if the real price is higher, so a premium name can't
+ *  surprise-charge. Contacts default to the platform account's when omitted. */
+export interface RegisterDomainOptions {
+    years?: number;
+    autorenewEnabled?: boolean;
+    privacyEnabled?: boolean;
+    nameservers?: string[];
+    contacts?: {
+        registrant: DomainContact;
+        admin?: DomainContact;
+        tech?: DomainContact;
+        billing?: DomainContact;
+    };
+    purchasePrice?: number;
+    promoCode?: string;
+}
+/** Result of a domain registration. */
+export interface RegisteredDomainResult {
+    domain: {
+        domainName: string;
+        createDate?: string;
+        expireDate?: string;
+        autorenewEnabled?: boolean;
+        locked?: boolean;
+        privacyEnabled?: boolean;
+        nameservers?: string[];
+        renewalPrice?: number;
+    };
+    order?: number;
+    totalPaid?: number;
+}
+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[];
+    }>;
+    /** Search domain availability + pricing to buy. A `query` with a dot is an
+     *  exact check ("acme.com"); a bare keyword ("acme") returns suggestions.
+     *  Requires the registrar (name.com) to be configured on the control plane. */
+    search(query: string, opts?: {
+        suggest?: boolean;
+        tldFilter?: string[];
+    }): Promise<{
+        results: DomainAvailability[];
+    }>;
+    /** REGISTER (buy) a domain for your end-customer. Spends money on the
+     *  platform's registrar account; requires a paid plan. Buying does not by
+     *  itself serve the app — attach a host with `add()` afterward. */
+    register(domainName: string, opts?: RegisterDomainOptions): Promise<RegisteredDomainResult>;
+}
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
     auth: AuthInfo<R>;
     stream: Stream;
@@ -789,6 +923,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.7",
   "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,13 @@ 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,
+  DomainAvailability,
+  DomainContact,
+  RegisterDomainOptions,
+  RegisteredDomainResult,
 } from "./types";

package/src/runtime.ts

@@ -31,6 +31,11 @@ import type {
   Rooms,
   Workflows,
   Connections,
+  Domains,
+  TenantDomainResult,
+  DomainAvailability,
+  RegisterDomainOptions,
+  RegisteredDomainResult,
   QueryCtx,
   MutationCtx,
   ActionCtx,
@@ -1056,6 +1061,80 @@ 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", {}),
+    search: (query: string, opts?: { suggest?: boolean; tldFilter?: string[] }) =>
+      call<{ results: DomainAvailability[] }>("searchAvailableDomains", {
+        query,
+        ...(opts ?? {}),
+      }),
+    register: (domainName: string, opts?: RegisterDomainOptions) =>
+      call<RegisteredDomainResult>("registerCustomerDomain", {
+        domainName,
+        ...(opts ?? {}),
+      }),
+  };
+}
+
 function buildActionCtx(
   callId: string,
   auth: AuthInfo,
@@ -1089,6 +1168,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,143 @@ 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
+ * ```
+ */
+/** One domain-availability / pricing result from a search. */
+export interface DomainAvailability {
+  domainName: string;
+  sld: string;
+  tld: string;
+  purchasable: boolean;
+  premium?: boolean;
+  /** First-term price (USD), when purchasable. */
+  purchasePrice?: number;
+  renewalPrice?: number;
+  purchaseType?: string;
+  /** Why it isn't purchasable, when unavailable. */
+  reason?: string | null;
+}
+
+/** A registrant/admin/tech/billing contact for a domain registration. */
+export interface DomainContact {
+  firstName: string;
+  lastName: string;
+  companyName?: string;
+  address1: string;
+  address2?: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+  email: string;
+  phone: string;
+  fax?: string;
+}
+
+/** Options for {@link Domains.register}. `purchasePrice` is a price ceiling —
+ *  registration is refused if the real price is higher, so a premium name can't
+ *  surprise-charge. Contacts default to the platform account's when omitted. */
+export interface RegisterDomainOptions {
+  years?: number;
+  autorenewEnabled?: boolean;
+  privacyEnabled?: boolean;
+  nameservers?: string[];
+  contacts?: {
+    registrant: DomainContact;
+    admin?: DomainContact;
+    tech?: DomainContact;
+    billing?: DomainContact;
+  };
+  purchasePrice?: number;
+  promoCode?: string;
+}
+
+/** Result of a domain registration. */
+export interface RegisteredDomainResult {
+  domain: {
+    domainName: string;
+    createDate?: string;
+    expireDate?: string;
+    autorenewEnabled?: boolean;
+    locked?: boolean;
+    privacyEnabled?: boolean;
+    nameservers?: string[];
+    renewalPrice?: number;
+  };
+  order?: number;
+  totalPaid?: number;
+}
+
+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[] }>;
+  /** Search domain availability + pricing to buy. A `query` with a dot is an
+   *  exact check ("acme.com"); a bare keyword ("acme") returns suggestions.
+   *  Requires the registrar (name.com) to be configured on the control plane. */
+  search(
+    query: string,
+    opts?: { suggest?: boolean; tldFilter?: string[] },
+  ): Promise<{ results: DomainAvailability[] }>;
+  /** REGISTER (buy) a domain for your end-customer. Spends money on the
+   *  platform's registrar account; requires a paid plan. Buying does not by
+   *  itself serve the app — attach a host with `add()` afterward. */
+  register(
+    domainName: string,
+    opts?: RegisterDomainOptions,
+  ): Promise<RegisteredDomainResult>;
+}
+
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
   auth: AuthInfo<R>;
   stream: Stream;
@@ -887,6 +1024,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}. */