@myapihq/sdk 1.1.0-wip.4 → 1.2.0

package/src/company.ts

@@ -0,0 +1,48 @@
+// Scaffolded from schema by scripts/scaffold-sdk.js — DO NOT remove the
+// EXPOSES array (the coverage tool verifies it against the live schema).
+// Types and function names ARE editable; re-running the scaffolder against
+// a service whose config has been changed will diff vs. existing file
+// (use --dry-run to inspect).
+
+import { request } from './client';
+import { COMPANY_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+import type { SearchFilter } from './audience';
+import type { Person } from './people';
+
+export const EXPOSES: Exposes = [
+  'POST /company/orgs/{org_id}/search',
+  'GET /company/orgs/{org_id}/{company_id}',
+];
+
+import type { Location, PersonCompany } from './people';
+
+// Company is the same shape as PersonCompany (a person's embedded company)
+// with an optional embedded people array when include_people=N is passed.
+export interface Company extends PersonCompany {
+  people?: Person[]; // present when include_people=N is passed
+}
+
+export interface CompanySearchResult {
+  companies: Company[];
+  total: number;
+  limit: number;
+  offset: number;
+  has_more: boolean;
+}
+
+export interface CompanySearchOptions extends SearchFilter {
+  include_people?: number; // 0..10; embed up to N people per company
+}
+
+export async function searchCompanies(apiKey: string, orgId: string, options: CompanySearchOptions): Promise<CompanySearchResult> {
+  return request('POST', `${BASE_URL}/company/orgs/${encodeURIComponent(orgId)}/search`, apiKey, options);
+}
+
+export async function getCompany(apiKey: string, orgId: string, companyId: string, include_people?: number): Promise<Company> {
+  const _url = include_people != null
+    ? `${BASE_URL}/company/orgs/${encodeURIComponent(orgId)}/${encodeURIComponent(companyId)}?include_people=${encodeURIComponent(String(include_people))}`
+    : `${BASE_URL}/company/orgs/${encodeURIComponent(orgId)}/${encodeURIComponent(companyId)}`;
+  return request('GET', _url, apiKey);
+}

package/src/config.ts

@@ -1,4 +1,15 @@
-export const HQ_BASE     = process.env.MYAPI_HQ_URL     ?? process.env.MYAPI_API_BASE ?? 'https://api.myapihq.com';
+// Service base URLs. Today's reality: all primitives are served from the
+// single `api.myapihq.com` gateway; per-service brand hosts
+// (e.g. api.myllmapi.com) are aspirational and only some are wired in DNS
+// + routed correctly. We default to the working hosts where they exist,
+// and to the gateway where they don't (LLM, DATABASE, CRM, PEOPLE,
+// COMPANY, AUDIENCE). The MYAPI_*_URL env vars stay as overrides for
+// local dev — `source scripts/local-env.sh` still points everything at
+// localhost:8080 regardless of the prod default.
+
+const GATEWAY = 'https://api.myapihq.com';
+
+export const HQ_BASE     = process.env.MYAPI_HQ_URL     ?? process.env.MYAPI_API_BASE ?? GATEWAY;
 export const DOMAIN_BASE  = process.env.MYAPI_DOMAIN_URL  ?? 'https://api.mydomainapi.com';
 export const FUNNEL_BASE  = process.env.MYAPI_FUNNEL_URL  ?? 'https://api.myfunnelapi.com';
 export const IMAGE_BASE   = process.env.MYAPI_IMAGE_URL   ?? 'https://api.myimageapi.com';
@@ -8,3 +19,12 @@ export const EMAIL_BASE   = process.env.MYAPI_EMAIL_URL   ?? 'https://api.myemai
 export const STORAGE_BASE = process.env.MYAPI_STORAGE_URL ?? 'https://api.mystorageapi.com';
 export const URL_BASE     = process.env.MYAPI_URL_URL     ?? 'https://api.myurlto.com';
 export const PIXEL_BASE   = process.env.MYAPI_PIXEL_URL   ?? 'https://api.mypixelapi.com';
+// Per-service hosts below either don't resolve in DNS or 404 the routes;
+// served via the gateway until backend wires the brand routing. Flip back
+// to per-service hosts when DNS is sound and routes verified there.
+export const PEOPLE_BASE  = process.env.MYAPI_PEOPLE_URL  ?? GATEWAY;
+export const COMPANY_BASE = process.env.MYAPI_COMPANY_URL ?? GATEWAY;
+export const AUDIENCE_BASE= process.env.MYAPI_AUDIENCE_URL?? GATEWAY;
+export const LLM_BASE     = process.env.MYAPI_LLM_URL     ?? GATEWAY;
+export const DATABASE_BASE= process.env.MYAPI_DATABASE_URL?? GATEWAY;
+export const CRM_BASE     = process.env.MYAPI_CRM_URL     ?? GATEWAY;

package/src/crm.ts

@@ -0,0 +1,235 @@
+import { request } from './client';
+import { CRM_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+export const EXPOSES: Exposes = [
+  'POST /crm/orgs/{org_id}/contacts',
+  'POST /crm/orgs/{org_id}/contacts/promote',
+  'POST /crm/orgs/{org_id}/contacts/search',
+  'GET /crm/orgs/{org_id}/contacts/{id}',
+  'PATCH /crm/orgs/{org_id}/contacts/{id}',
+  'DELETE /crm/orgs/{org_id}/contacts/{id}',
+  'GET /crm/orgs/{org_id}/contacts/{id}/events',
+  'POST /crm/orgs/{org_id}/companies',
+  'POST /crm/orgs/{org_id}/companies/promote',
+  'POST /crm/orgs/{org_id}/companies/search',
+  'GET /crm/orgs/{org_id}/companies/{id}',
+  'PATCH /crm/orgs/{org_id}/companies/{id}',
+  'DELETE /crm/orgs/{org_id}/companies/{id}',
+];
+
+// Shared enums — fixed sets. Lifecycle stage is the same enum for contacts
+// and companies (Simon's call: keep it simple, easier for agents).
+export type LifecycleStage =
+  | 'cold'
+  | 'warm'
+  | 'qualified'
+  | 'customer'
+  | 'churned';
+
+export type ContactSource =
+  | 'goldfox'
+  | 'email'
+  | 'pixel'
+  | 'webhook'
+  | 'manual';
+
+// Reserved set of event kinds. Agents cannot write these directly — they
+// are emitted by the platform when state changes (stage_changed) or the
+// underlying service completes (email_sent, webhook_received, etc.).
+export type EventKind =
+  | 'created'
+  | 'promoted'
+  | 'stage_changed'
+  | 'email_sent'
+  | 'email_opened'
+  | 'email_clicked'
+  | 'email_replied'
+  | 'pixel_visit'
+  | 'webhook_received';
+
+// Goldfox enrichment is a live join — the response embeds the current
+// Goldfox row when goldfox_person_id is set. v1: returns null until the
+// BQ get-by-id helper lands backend-side. The field shape will become
+// the existing Person from people.ts once enabled.
+export interface Contact {
+  id: string;
+  org_id: string;
+  email: string | null;
+  first_name: string | null;
+  last_name: string | null;
+  company_id: string | null;
+  lifecycle_stage: LifecycleStage;
+  custom: Record<string, unknown>;
+  source: ContactSource;
+  goldfox_person_id: string | null;
+  goldfox_person?: unknown | null; // deferred until BQ helper lands
+  created_at: string;
+  updated_at: string;
+  last_engagement_at?: string | null; // only set after engagement events (email/pixel/webhook)
+  deleted_at?: string | null;          // soft-delete marker
+}
+
+export interface Company {
+  id: string;
+  org_id: string;
+  domain: string | null;
+  name: string | null;
+  lifecycle_stage: LifecycleStage;
+  custom: Record<string, unknown>;
+  source: ContactSource;
+  goldfox_company_id: string | null;   // for Goldfox-sourced rows this equals the domain
+  goldfox_company?: unknown | null;
+  created_at: string;
+  updated_at: string;
+  deleted_at?: string | null;
+}
+
+export interface ContactEvent {
+  id: string;
+  contact_id: string;
+  kind: EventKind;
+  payload: Record<string, unknown>;
+  at: string;
+}
+
+// ── Inputs ────────────────────────────────────────────────────────────────
+
+export interface CreateContactInput {
+  email?: string | null;
+  first_name?: string;
+  last_name?: string;
+  company_id?: string;             // override the auto-link by domain
+  lifecycle_stage?: LifecycleStage;
+  custom?: Record<string, unknown>;
+  source?: ContactSource;          // defaults to 'manual' server-side
+}
+
+export interface UpdateContactInput {
+  first_name?: string | null;
+  last_name?: string | null;
+  company_id?: string | null;
+  lifecycle_stage?: LifecycleStage;
+  custom?: Record<string, unknown>;
+  deleted_at?: null;               // pass explicit null to restore a soft-deleted contact
+}
+
+export interface ContactSearchFilter {
+  lifecycle_stage?: LifecycleStage[];
+  source?: ContactSource[];
+  email?: string;
+  company_id?: string;
+  min_last_engagement_days?: number;  // engaged within N days
+  max_last_engagement_days?: number;  // last engaged > N days ago — re-engagement filter
+  include_deleted?: boolean;          // default false
+  limit?: number;
+  offset?: number;
+}
+
+export interface ContactSearchResult {
+  contacts: Contact[];
+  total: number;
+}
+
+export interface CreateCompanyInput {
+  domain?: string | null;
+  name?: string;
+  lifecycle_stage?: LifecycleStage;
+  custom?: Record<string, unknown>;
+  source?: ContactSource;
+}
+
+export interface UpdateCompanyInput {
+  name?: string | null;
+  lifecycle_stage?: LifecycleStage;
+  custom?: Record<string, unknown>;
+  deleted_at?: null;
+}
+
+export interface CompanySearchFilter {
+  lifecycle_stage?: LifecycleStage[];
+  source?: ContactSource[];
+  domain?: string;
+  include_deleted?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface CompanySearchResult {
+  companies: Company[];
+  total: number;
+}
+
+export interface EventsResponse {
+  events: ContactEvent[];
+  next_cursor?: string;
+}
+
+export interface ListEventsOptions {
+  limit?: number;       // 1-200, default 50
+  cursor?: string;
+  kind?: EventKind;
+}
+
+// ── Contacts ──────────────────────────────────────────────────────────────
+
+export async function createContact(apiKey: string, orgId: string, input: CreateContactInput): Promise<Contact> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts`, apiKey, input);
+}
+
+export async function getContact(apiKey: string, orgId: string, id: string): Promise<Contact> {
+  return request('GET', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}`, apiKey);
+}
+
+export async function updateContact(apiKey: string, orgId: string, id: string, patch: UpdateContactInput): Promise<Contact> {
+  return request('PATCH', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}`, apiKey, patch);
+}
+
+export async function deleteContact(apiKey: string, orgId: string, id: string): Promise<void> {
+  return request('DELETE', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}`, apiKey);
+}
+
+export async function searchContacts(apiKey: string, orgId: string, filter: ContactSearchFilter = {}): Promise<ContactSearchResult> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/search`, apiKey, filter);
+}
+
+export async function promoteContact(apiKey: string, orgId: string, goldfoxPersonId: string): Promise<Contact> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/promote`, apiKey, { goldfox_person_id: goldfoxPersonId });
+}
+
+export async function getContactEvents(apiKey: string, orgId: string, id: string, opts: ListEventsOptions = {}): Promise<EventsResponse> {
+  const qs = new URLSearchParams();
+  if (opts.limit != null) qs.append('limit', String(opts.limit));
+  if (opts.cursor != null) qs.append('cursor', opts.cursor);
+  if (opts.kind != null) qs.append('kind', opts.kind);
+  const q = qs.toString();
+  const url = `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}/events${q ? `?${q}` : ''}`;
+  return request('GET', url, apiKey);
+}
+
+// ── Companies ─────────────────────────────────────────────────────────────
+
+export async function createCompany(apiKey: string, orgId: string, input: CreateCompanyInput): Promise<Company> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies`, apiKey, input);
+}
+
+export async function getCompany(apiKey: string, orgId: string, id: string): Promise<Company> {
+  return request('GET', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies/${encodeURIComponent(id)}`, apiKey);
+}
+
+export async function updateCompany(apiKey: string, orgId: string, id: string, patch: UpdateCompanyInput): Promise<Company> {
+  return request('PATCH', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies/${encodeURIComponent(id)}`, apiKey, patch);
+}
+
+export async function deleteCompany(apiKey: string, orgId: string, id: string): Promise<void> {
+  return request('DELETE', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies/${encodeURIComponent(id)}`, apiKey);
+}
+
+export async function searchCompanies(apiKey: string, orgId: string, filter: CompanySearchFilter = {}): Promise<CompanySearchResult> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies/search`, apiKey, filter);
+}
+
+// Goldfox company id IS its domain (Simon's note in routes.md).
+export async function promoteCompany(apiKey: string, orgId: string, domain: string): Promise<Company> {
+  return request('POST', `${BASE_URL}/crm/orgs/${encodeURIComponent(orgId)}/companies/promote`, apiKey, { goldfox_company_id: domain });
+}

package/src/database.ts

@@ -0,0 +1,103 @@
+import { request } from './client';
+import { DATABASE_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+export const EXPOSES: Exposes = [
+  'GET /database/orgs/{org_id}/namespaces',
+  'POST /database/orgs/{org_id}/namespaces',
+  'GET /database/orgs/{org_id}/namespaces/{ns}',
+  'DELETE /database/orgs/{org_id}/namespaces/{ns}',
+  'GET /database/orgs/{org_id}/namespaces/{ns}/keys',
+  'GET /database/orgs/{org_id}/namespaces/{ns}/keys/{key}',
+  'PUT /database/orgs/{org_id}/namespaces/{ns}/keys/{key}',
+  'DELETE /database/orgs/{org_id}/namespaces/{ns}/keys/{key}',
+];
+
+// Per-value JSON size cap. Mirrored server-side. Surfaced here so the CLI
+// can fail fast before round-trip.
+export const MAX_VALUE_BYTES = 256 * 1024;
+
+export interface Namespace {
+  name: string;
+  org_id: string;
+  key_count: number; // approximate; eventually consistent
+  created_at: string;
+}
+
+export interface KeyEntry {
+  key: string;
+  value?: unknown;       // present when values=true was requested or on get
+  etag: string;
+  updated_at: string;
+}
+
+export interface ListKeysOptions {
+  prefix?: string;
+  limit?: number;        // 1-1000, default 50
+  cursor?: string;       // opaque from previous response
+  values?: boolean;      // default false
+}
+
+export interface ListKeysResponse {
+  keys: KeyEntry[];
+  next_cursor?: string;  // present when more results exist
+}
+
+export interface ListNamespacesResponse {
+  namespaces: Namespace[];
+}
+
+export async function listNamespaces(apiKey: string, orgId: string): Promise<ListNamespacesResponse> {
+  return request('GET', `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces`, apiKey);
+}
+
+export async function createNamespace(apiKey: string, orgId: string, name: string): Promise<Namespace> {
+  return request('POST', `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces`, apiKey, { name });
+}
+
+export async function getNamespace(apiKey: string, orgId: string, name: string): Promise<Namespace> {
+  return request('GET', `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(name)}`, apiKey);
+}
+
+export async function deleteNamespace(apiKey: string, orgId: string, name: string): Promise<void> {
+  return request('DELETE', `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(name)}`, apiKey);
+}
+
+export async function listKeys(apiKey: string, orgId: string, ns: string, opts: ListKeysOptions = {}): Promise<ListKeysResponse> {
+  const qs = new URLSearchParams();
+  if (opts.prefix != null) qs.append('prefix', opts.prefix);
+  if (opts.limit != null) qs.append('limit', String(opts.limit));
+  if (opts.cursor != null) qs.append('cursor', opts.cursor);
+  if (opts.values) qs.append('values', 'true');
+  const q = qs.toString();
+  const url = `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(ns)}/keys${q ? `?${q}` : ''}`;
+  return request('GET', url, apiKey);
+}
+
+export async function getKey(apiKey: string, orgId: string, ns: string, key: string): Promise<KeyEntry> {
+  return request('GET', `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(ns)}/keys/${encodeURIComponent(key)}`, apiKey);
+}
+
+// `ifMatch` enables compare-and-swap: server returns 412 ETAG_MISMATCH when
+// the stored etag differs. Omit for last-write-wins.
+export async function putKey(apiKey: string, orgId: string, ns: string, key: string, value: unknown, ifMatch?: string): Promise<KeyEntry> {
+  const headers = ifMatch ? { 'If-Match': ifMatch } : undefined;
+  return request(
+    'PUT',
+    `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(ns)}/keys/${encodeURIComponent(key)}`,
+    apiKey,
+    { value },
+    headers,
+  );
+}
+
+export async function deleteKey(apiKey: string, orgId: string, ns: string, key: string, ifMatch?: string): Promise<void> {
+  const headers = ifMatch ? { 'If-Match': ifMatch } : undefined;
+  return request(
+    'DELETE',
+    `${BASE_URL}/database/orgs/${encodeURIComponent(orgId)}/namespaces/${encodeURIComponent(ns)}/keys/${encodeURIComponent(key)}`,
+    apiKey,
+    undefined,
+    headers,
+  );
+}

package/src/domain.ts

@@ -1,5 +1,18 @@
 import { request } from './client';
 import { DOMAIN_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+export const EXPOSES: Exposes = [
+  'GET /domain/orgs/{org_id}/list',
+  'GET /domain/orgs/{org_id}/check/available/{name}',
+  'POST /domain/orgs/{org_id}/register',
+  'POST /domain/orgs/{org_id}/import',
+  'POST /domain/orgs/{org_id}/{domain}/assign',
+  'POST /domain/orgs/{org_id}/{domain}/renew',
+  'GET /domain/orgs/{org_id}/{domain}/settings',
+  'POST /domain/orgs/{org_id}/{domain}/settings',
+  'GET /domain/orgs/{org_id}/{domain}/status',
+];
 
 
 
@@ -21,12 +34,41 @@ export interface DomainSettings {
   is_robots_txt_managed: boolean;
 }
 
+// ICANN-required WHOIS contact info for domain registration. Sent in the
+// register-domain request body when REGISTRAR_PROVIDER=cloudflare is set
+// server-side; ignored (but accepted) under the legacy OpenProvider path.
+// The CF account holds the zone; this is the WHOIS registrant.
+export interface Registrant {
+  name: string;
+  email: string;
+  phone: string;          // E.164 format recommended (e.g. "+33612345678")
+  street: string;
+  city: string;
+  state?: string;         // Required for US / CA registrants; optional elsewhere.
+  postal_code: string;
+  country_code: string;   // ISO 3166-1 alpha-2 (e.g. "US", "DE", "FR")
+  organization?: string;  // Optional organization name (WHOIS "Registrant Organization" field).
+}
+
+export interface RegisterDomainInput {
+  years?: number;
+  registrant: Registrant;
+}
+
 export async function checkDomain(apiKey: string, orgId: string, domain: string): Promise<{ available: boolean; price_cents: number }> {
   return request('GET', `${BASE_URL}/domain/orgs/${encodeURIComponent(orgId)}/check/available/${encodeURIComponent(domain)}`, apiKey);
 }
 
-export async function registerDomain(apiKey: string, orgId: string, domain: string, years?: number): Promise<DomainRecord> {
-  return request('POST', `${BASE_URL}/domain/orgs/${encodeURIComponent(orgId)}/register`, apiKey, { domain, years });
+export async function registerDomain(apiKey: string, orgId: string, domain: string, input: RegisterDomainInput): Promise<DomainRecord> {
+  return request('POST', `${BASE_URL}/domain/orgs/${encodeURIComponent(orgId)}/register`, apiKey, {
+    domain,
+    years: input.years,
+    registrant: input.registrant,
+  });
+}
+
+export async function renewDomain(apiKey: string, orgId: string, domain: string): Promise<DomainRecord> {
+  return request('POST', `${BASE_URL}/domain/orgs/${encodeURIComponent(orgId)}/${encodeURIComponent(domain)}/renew`, apiKey);
 }
 
 export async function importDomain(apiKey: string, orgId: string, payload: { domain: string; namecheap_api_user?: string; namecheap_api_key?: string; }): Promise<DomainRecord> {

package/src/email.ts

@@ -1,5 +1,49 @@
 import { request } from './client';
 import { EMAIL_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+export const EXPOSES: Exposes = [
+  // Mailbox / sending activation
+  'POST /email/mailboxes/create',
+  'GET /email/mailboxes',
+  'POST /email/sending/activate',
+  // Send + read
+  'POST /email/send',
+  'GET /email/status/{message_id}',
+  'GET /email/sent',
+  'GET /email/inbox/{address}',
+  'GET /email/outbox/{address}',
+  'GET /email/message/{message_id}',
+  // Warmup
+  'POST /email/warmup/start',
+  'POST /email/warmup/pause',
+  'POST /email/warmup/resume',
+  'POST /email/warmup/stop',
+  'GET /email/warmup/stats/{address}',
+  // Templates
+  'POST /email/orgs/{org_id}/templates/generate',
+  'GET /email/orgs/{org_id}/template-jobs/{job_id}',
+  'GET /email/orgs/{org_id}/templates',
+  'GET /email/orgs/{org_id}/templates/{template_id}',
+  'POST /email/orgs/{org_id}/templates/{template_id}/edit',
+  'POST /email/orgs/{org_id}/templates/{template_id}/send-test',
+  'DELETE /email/orgs/{org_id}/templates/{template_id}',
+  'GET /email/templates/{template_id}/preview',
+  // Campaigns
+  'POST /email/orgs/{org_id}/campaigns',
+  'GET /email/orgs/{org_id}/campaigns',
+  'GET /email/orgs/{org_id}/campaigns/{campaign_id}',
+  'PATCH /email/orgs/{org_id}/campaigns/{campaign_id}',
+  'POST /email/orgs/{org_id}/campaigns/{campaign_id}/contacts/upload-list',
+  'POST /email/orgs/{org_id}/campaigns/{campaign_id}/contacts/upload-file',
+  'GET /email/orgs/{org_id}/campaigns/{campaign_id}/contacts/status',
+  'POST /email/orgs/{org_id}/campaigns/{campaign_id}/start',
+  'POST /email/orgs/{org_id}/campaigns/{campaign_id}/pause',
+  'POST /email/orgs/{org_id}/campaigns/{campaign_id}/resume',
+  'GET /email/orgs/{org_id}/campaigns/{campaign_id}/stats',
+  // Verify
+  'POST /email/orgs/{org_id}/verify',
+];
 
 export interface EmailMessage { message_id: string; from: string; subject: string; body?: string; received_at: string }
 export interface EmailTemplate { id: string; name: string; subject: string; preview_url: string; created_at: string; updated_at: string }
@@ -12,6 +56,40 @@ export interface CampaignStats {
   engagement: { sent: number; opens: number; clicks: number; page_visits: number };
 }
 
+// ── Email verification ──────────────────────────────────────────────────────
+//
+// Synchronous single-address verification — syntax + DNS + a Microsoft
+// GetCredentialType probe. Cheap layer only: ~50% of inputs return a
+// definitive verdict in <1s; the rest get verdict='unknown' with
+// smtp_recommended=true, suggesting a downstream SMTP probe (not in this
+// API today).
+
+export type VerifyVerdict = 'deliverable' | 'undeliverable' | 'unknown';
+
+export interface VerifyChecks {
+  syntax: { valid: boolean; detail?: string };
+  dns?: { valid: boolean; mx_records?: string[] };
+  microsoft?: {
+    verdict: string;          // e.g. 'federated_unknown', 'not_microsoft_domain'
+    if_exists_result: number; // Microsoft GetCredentialType enum
+    domain_type: number;
+    federated: boolean;
+  };
+}
+
+export interface VerifyResult {
+  email: string;
+  verdict: VerifyVerdict;
+  confidence: number;       // 0..1
+  smtp_recommended: boolean;
+  checks: VerifyChecks;
+  elapsed_ms: number;
+}
+
+export async function verifyEmail(apiKey: string, orgId: string, email: string): Promise<VerifyResult> {
+  return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/verify`, apiKey, { email });
+}
+
 // ── Mailbox ops (account-scoped) ─────────────────────────────────────────────
 
 export async function createMailbox(apiKey: string, domain: string, username: string, displayName?: string): Promise<{ address: string; created_at: string }> {
@@ -96,6 +174,12 @@ export async function getTemplate(apiKey: string, orgId: string, templateId: str
   return request('GET', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates/${encodeURIComponent(templateId)}`, apiKey);
 }
 
+// Public preview — no auth required. The endpoint is unauthenticated per
+// the OpenAPI schema; access is gated by the unguessable template_id.
+export async function getTemplatePreview(templateId: string): Promise<{ html?: string; subject?: string; preview_url?: string } & Record<string, unknown>> {
+  return request('GET', `${BASE_URL}/email/templates/${encodeURIComponent(templateId)}/preview`, undefined);
+}
+
 export async function editTemplate(apiKey: string, orgId: string, templateId: string, prompt: string): Promise<{ template_id: string; preview_url: string }> {
   return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates/${encodeURIComponent(templateId)}/edit`, apiKey, { prompt });
 }

package/src/exposes.ts

@@ -0,0 +1,16 @@
+// OpenAPI-templated endpoint declaration for SDK service modules.
+//
+// Each service module (hq, domain, funnel, ...) exports an `EXPOSES: Exposes`
+// array listing the backend endpoints reachable through that module's
+// functions. The integrations coverage tool walks these to verify CLI ↔ SDK
+// parity (S-108).
+//
+// Form: `<METHOD> <PATH>` where path uses `{name}` for variable segments
+// matching OpenAPI 3.x style.
+//
+// Mirrors packages/cli/src/exposes.ts — kept duplicated to avoid runtime
+// dependencies between the packages (the SDK has zero runtime deps per NFR-005).
+
+export type Endpoint = `${'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'} /${string}`;
+
+export type Exposes = readonly Endpoint[];

package/src/funnel.ts

@@ -1,5 +1,16 @@
 import { request } from './client';
 import { FUNNEL_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+export const EXPOSES: Exposes = [
+  'POST /funnel/orgs/{org_id}/funnels',
+  'GET /funnel/orgs/{org_id}/funnels',
+  'GET /funnel/orgs/{org_id}/funnels/{funnel_id}',
+  'DELETE /funnel/orgs/{org_id}/funnels/{funnel_id}',
+  'POST /funnel/orgs/{org_id}/funnels/{funnel_id}/push-page',
+  'POST /funnel/orgs/{org_id}/funnels/{funnel_id}/verify',
+  'GET /funnel/orgs/{org_id}/funnels/{funnel_id}/pages',
+];
 
 
 
@@ -27,6 +38,29 @@ export async function deleteFunnel(apiKey: string, orgId: string, funnelId: stri
 export async function pushFunnelPage(apiKey: string, orgId: string, funnelId: string, payload: { slug: string; html: string }): Promise<{ url: string }> {
   return request('POST', `${BASE_URL}/funnel/orgs/${encodeURIComponent(orgId)}/funnels/${encodeURIComponent(funnelId)}/push-page`, apiKey, payload);
 }
+
+export interface FunnelPage {
+  slug: string;
+  url?: string;
+  published_at?: string;
+  updated_at?: string;
+  // Backend may include other fields; we type the common ones and let the
+  // rest pass through for printJson() / printTable() consumers.
+  [key: string]: unknown;
+}
+
+export async function listFunnelPages(apiKey: string, orgId: string, funnelId: string): Promise<FunnelPage[]> {
+  // Backend returns `{ pages: [...] }` for this endpoint (every other list
+  // endpoint returns a flat array). Unwrap so the SDK's contract matches the
+  // rest — callers expect an array.
+  const res = await request<{ pages?: FunnelPage[] } | FunnelPage[]>(
+    'GET',
+    `${BASE_URL}/funnel/orgs/${encodeURIComponent(orgId)}/funnels/${encodeURIComponent(funnelId)}/pages`,
+    apiKey,
+  );
+  if (Array.isArray(res)) return res;
+  return res?.pages ?? [];
+}
 export async function verifyFunnel(apiKey: string, orgId: string, funnelId: string, opts?: { html?: string; slug?: string }): Promise<VerifyResult> {
   return request('POST', `${BASE_URL}/funnel/orgs/${encodeURIComponent(orgId)}/funnels/${encodeURIComponent(funnelId)}/verify`, apiKey, opts || {});
 }