@myapihq/sdk 2.4.0 → 2.4.2

package/src/email.ts

@@ -1,247 +0,0 @@
-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',
-  'DELETE /email/mailboxes/{address}',
-  'PUT /email/mailboxes/{address}/forwarding',
-  'DELETE /email/mailboxes/{address}/forwarding',
-  'POST /email/sending/activate',
-  'POST /email/orgs/{org_id}/domains/{domain}/mail-server-resync',
-  // 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',
-  // Verify
-  'POST /email/orgs/{org_id}/verify',
-  'POST /email/orgs/{org_id}/verify-bulk',
-  'GET /email/orgs/{org_id}/verify-jobs/{id}',
-];
-
-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 }
-
-// ── 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 });
-}
-
-// One address's outcome in a bulk-verification job.
-export interface BulkVerifyResult {
-  email: string;
-  verdict: string;          // deliverable | undeliverable | risky | unknown
-  confidence: number;
-  source: string;           // phase1 | strategist | smtp
-  classification?: string;
-  mx?: string;
-  rcpt_code?: number;
-  catch_all?: boolean;
-  detail?: string;
-}
-
-export interface VerifyJob {
-  job_id: string;
-  status: string;           // pending | running | done | failed
-  total: number;
-  completed?: number;
-  catch_all?: boolean;
-  results?: BulkVerifyResult[];
-  error?: string;
-}
-
-// verifyBulk kicks off an asynchronous bulk verification (1-500 addresses)
-// and returns immediately with a job_id. `catchAll` toggles the catch-all
-// check on SMTP-probed addresses (default true). Poll getVerifyJob for
-// status + results.
-export async function verifyBulk(apiKey: string, orgId: string, emails: string[], catchAll?: boolean): Promise<VerifyJob> {
-  const body: { emails: string[]; catch_all?: boolean } = { emails };
-  if (catchAll !== undefined) body.catch_all = catchAll;
-  return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/verify-bulk`, apiKey, body);
-}
-
-export async function getVerifyJob(apiKey: string, orgId: string, jobId: string): Promise<VerifyJob> {
-  return request('GET', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/verify-jobs/${encodeURIComponent(jobId)}`, apiKey);
-}
-
-// ── Mailbox ops (account-scoped) ─────────────────────────────────────────────
-
-export async function createMailbox(apiKey: string, domain: string, username: string, displayName?: string): Promise<{ address: string; created_at: string }> {
-  return request('POST', `${BASE_URL}/email/mailboxes/create`, apiKey, { domain, username, display_name: displayName });
-}
-
-// Backend (2026-06-06): idempotent — 204 whether the mailbox existed or not.
-// May return 409 MAILBOX_IN_USE if the address is still referenced server-side.
-export async function deleteMailbox(apiKey: string, address: string): Promise<void> {
-  return request('DELETE', `${BASE_URL}/email/mailboxes/${encodeURIComponent(address)}`, apiKey);
-}
-
-// Backend (2026-06-06): re-run Stalwart provisioning for a domain. Use when
-// mailbox-create on a domain returns DOMAIN_NOT_MAIL_READY /
-// MAILBOX_PROVISION_FAILED, or when the inbox endpoint returns
-// "mail server error" on a domain whose `email_infra_ready` flag is stale.
-// Idempotent.
-export async function mailServerResync(apiKey: string, orgId: string, domain: string): Promise<{ ok: boolean } & Record<string, unknown>> {
-  return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/domains/${encodeURIComponent(domain)}/mail-server-resync`, apiKey);
-}
-
-export async function listMailboxes(apiKey: string, options?: { domain?: string; filter?: 'unassigned' }): Promise<{ address: string; created_at: string }[]> {
-  const query = new URLSearchParams();
-  if (options?.domain) query.append('domain', options.domain);
-  if (options?.filter) query.append('filter', options.filter);
-  const qStr = query.toString();
-  return request('GET', `${BASE_URL}/email/mailboxes${qStr ? '?' + qStr : ''}`, apiKey);
-}
-
-export async function activateSending(apiKey: string, address: string): Promise<{
-  address: string;
-  sending_enabled: boolean;
-  emails_quota_remaining: number;
-}> {
-  return request('POST', `${BASE_URL}/email/sending/activate`, apiKey, { address });
-}
-
-// setForwarding redirects a copy of every incoming message to an external
-// address (server-side; the original is kept in the mailbox). `forwardTo`
-// must be a valid address and cannot equal the mailbox itself.
-export async function setForwarding(apiKey: string, address: string, forwardTo: string): Promise<{ address: string; forward_to: string }> {
-  return request('PUT', `${BASE_URL}/email/mailboxes/${encodeURIComponent(address)}/forwarding`, apiKey, { forward_to: forwardTo });
-}
-
-// deleteForwarding stops forwarding for a mailbox.
-export async function deleteForwarding(apiKey: string, address: string): Promise<void> {
-  return request('DELETE', `${BASE_URL}/email/mailboxes/${encodeURIComponent(address)}/forwarding`, apiKey);
-}
-
-// ── Sending and reading (account-scoped) ─────────────────────────────────────
-
-export async function sendEmail(apiKey: string, payload: { from: string; to: string[]; subject: string; html?: string; text?: string; template_id?: string; template_vars?: Record<string, string> }): Promise<{ message_id: string }> {
-  return request('POST', `${BASE_URL}/email/send`, apiKey, payload);
-}
-
-export async function getEmailStatus(apiKey: string, messageId: string): Promise<{ status: string; delivered_at?: string }> {
-  return request('GET', `${BASE_URL}/email/status/${encodeURIComponent(messageId)}`, apiKey);
-}
-
-export async function getSentEmails(apiKey: string, limit: number = 50, offset: number = 0): Promise<EmailMessage[]> {
-  return request('GET', `${BASE_URL}/email/sent?limit=${limit}&offset=${offset}`, apiKey);
-}
-
-export async function getInbox(apiKey: string, address: string): Promise<EmailMessage[]> {
-  return request('GET', `${BASE_URL}/email/inbox/${encodeURIComponent(address)}`, apiKey);
-}
-
-export async function getOutbox(apiKey: string, address: string): Promise<EmailMessage[]> {
-  return request('GET', `${BASE_URL}/email/outbox/${encodeURIComponent(address)}`, apiKey);
-}
-
-export async function getMessage(apiKey: string, messageId: string, address: string): Promise<EmailMessage> {
-  return request('GET', `${BASE_URL}/email/message/${encodeURIComponent(messageId)}?address=${encodeURIComponent(address)}`, apiKey);
-}
-
-// ── Warmup (account-scoped) ──────────────────────────────────────────────────
-
-export async function startWarmup(apiKey: string, address: string): Promise<{ warmup_status: string }> {
-  return request('POST', `${BASE_URL}/email/warmup/start`, apiKey, { address });
-}
-
-export async function pauseWarmup(apiKey: string, address: string): Promise<void> {
-  return request('POST', `${BASE_URL}/email/warmup/pause`, apiKey, { address });
-}
-
-export async function resumeWarmup(apiKey: string, address: string): Promise<void> {
-  return request('POST', `${BASE_URL}/email/warmup/resume`, apiKey, { address });
-}
-
-export async function stopWarmup(apiKey: string, address: string): Promise<void> {
-  return request('POST', `${BASE_URL}/email/warmup/stop`, apiKey, { address });
-}
-
-export async function getWarmupStats(apiKey: string, address: string): Promise<{ sent: number; landed_inbox: number; landed_spam: number; health_score: number }> {
-  return request('GET', `${BASE_URL}/email/warmup/stats/${encodeURIComponent(address)}`, apiKey);
-}
-
-// ── Templates (org-scoped — brand context drives generation) ─────────────────
-
-export async function generateTemplate(apiKey: string, orgId: string, payload: { prompt: string; name: string; }): Promise<{ job_id: string; template_id: string; status: string; preview_url: string }> {
-  return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates/generate`, apiKey, payload);
-}
-
-export async function getTemplateJobStatus(apiKey: string, orgId: string, jobId: string): Promise<{ status: 'processing' | 'completed' | 'failed'; template_id: string; result?: { subject: string; preview_url: string } }> {
-  return request('GET', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/template-jobs/${encodeURIComponent(jobId)}`, apiKey);
-}
-
-export async function getTemplate(apiKey: string, orgId: string, templateId: string): Promise<EmailTemplate> {
-  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 });
-}
-
-export async function sendTestEmail(apiKey: string, orgId: string, templateId: string, to: string): Promise<{ ok: boolean; message_id: string }> {
-  return request('POST', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates/${encodeURIComponent(templateId)}/send-test`, apiKey, { to });
-}
-
-export async function listTemplates(apiKey: string, orgId: string): Promise<EmailTemplate[]> {
-  return request('GET', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates`, apiKey);
-}
-
-export async function deleteTemplate(apiKey: string, orgId: string, templateId: string): Promise<void> {
-  return request('DELETE', `${BASE_URL}/email/orgs/${encodeURIComponent(orgId)}/templates/${encodeURIComponent(templateId)}`, apiKey);
-}

package/src/exposes.ts

@@ -1,16 +0,0 @@
-// 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/function.ts

@@ -1,141 +0,0 @@
-import { request, MyApiError } from './client';
-import { ApiResponse } from './types';
-import { FUNCTION_BASE as BASE_URL } from './config';
-import type { Exposes } from './exposes';
-
-// Backend: Story 1 (metadata + scoped API key) and Story 2/4/5 (deploy,
-// runs, env) per myapi-hq/internal/routes/function/. The /logs endpoint is
-// still pending — do not add forward-compat fields the backend will ignore.
-export const EXPOSES: Exposes = [
-  'POST /function/orgs/{org_id}/functions',
-  'GET /function/orgs/{org_id}/functions',
-  'GET /function/orgs/{org_id}/functions/{id}',
-  'DELETE /function/orgs/{org_id}/functions/{id}',
-  'POST /function/orgs/{org_id}/functions/{id}/bundle',
-  'POST /function/orgs/{org_id}/functions/{id}/env',
-  'GET /function/orgs/{org_id}/functions/{id}/runs',
-];
-
-export type TriggerType = 'http' | 'cron';
-
-// Mirrors the backend's `Function` struct in crud.go. `invocation_url`
-// stays an empty string until the function is deployed (uploadBundle).
-export interface Fn {
-  id: string;
-  org_id: string;
-  name: string;
-  trigger_type: TriggerType;
-  cron_schedule?: string;
-  invocation_url: string;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface CreatePayload {
-  name: string;                        // required; ^[a-z0-9][a-z0-9-]{0,49}$
-  trigger_type?: TriggerType;          // optional, defaults to 'http' server-side
-  cron_schedule?: string;              // required if trigger_type === 'cron'
-  // Optional slot allow-list narrowing the minted function key's grants
-  // (backend crud.go: CreateFunction `scopes`). Empty/omitted inherits the
-  // deploying caller's grants (legacy). Grants can never exceed the caller.
-  scopes?: string[];
-}
-
-// POST response envelope includes the scoped API key — returned ONCE. The
-// caller must persist it if they want to use it directly; the SDK does not
-// store it. The function's runtime shim (`globalThis.MYAPI`) uses this key
-// internally.
-export interface CreateResponse {
-  function: Fn;
-  scoped_api_key: string;
-  scoped_api_key_id: string;
-}
-
-// uploadBundle response. The scoped API key is ROTATED on every deploy —
-// the value here is fresh and the only time it is knowable. The previous
-// scoped key is revoked server-side.
-export interface DeployResponse {
-  function: Fn;
-  invocation_url: string;
-  scoped_api_key: string;
-}
-
-// One recorded invocation — mirrors the backend's `FunctionRun` struct.
-export interface FunctionRun {
-  id: string;
-  function_id: string;
-  invoked_at: string;
-  duration_ms?: number;
-  status?: string;
-  error_message?: string;
-}
-
-export async function createFunction(apiKey: string, orgId: string, payload: CreatePayload): Promise<CreateResponse> {
-  return request('POST', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions`, apiKey, payload);
-}
-
-export async function listFunctions(apiKey: string, orgId: string): Promise<Fn[]> {
-  return request('GET', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions`, apiKey);
-}
-
-export async function getFunction(apiKey: string, orgId: string, fnId: string): Promise<Fn> {
-  return request('GET', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}`, apiKey);
-}
-
-export async function deleteFunction(apiKey: string, orgId: string, fnId: string): Promise<void> {
-  return request('DELETE', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}`, apiKey);
-}
-
-// uploadBundle deploys a single-file JS bundle (Story 2). The backend
-// wraps it with the MYAPI shim and uploads to Cloudflare Workers. The
-// multipart field MUST be named `bundle`. Raw upload cap is 4MB.
-export async function uploadBundle(
-  apiKey: string,
-  orgId: string,
-  fnId: string,
-  bundle: Blob | Buffer | string,
-  filename = 'bundle.js',
-): Promise<DeployResponse> {
-  const formData = new FormData();
-  formData.append('bundle', new Blob([bundle as any], { type: 'application/javascript' }), filename);
-
-  const response = await fetch(
-    `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}/bundle`,
-    { method: 'POST', headers: { Authorization: `Bearer ${apiKey}` }, body: formData as any },
-  );
-
-  let result: any;
-  try {
-    result = await response.json();
-  } catch {
-    throw new MyApiError('invalid_json_response', response.status);
-  }
-  if (!response.ok || !result?.success) {
-    const err = result?.error;
-    const code = typeof err === 'object' ? (err?.code || 'unknown_error') : (err || 'unknown_error');
-    const detail = typeof err === 'object' ? err?.message : undefined;
-    throw new MyApiError(code, response.status, detail, typeof err === 'object' ? err : undefined);
-  }
-  return (result as ApiResponse<DeployResponse>).data as DeployResponse;
-}
-
-// setFunctionEnv writes a secret (Stripe key, etc.) as a Cloudflare Worker
-// Secret on the deployed script (Story 5). The function must already be
-// deployed. The value is never stored in MyAPI Postgres or returned.
-export async function setFunctionEnv(apiKey: string, orgId: string, fnId: string, name: string, value: string): Promise<void> {
-  return request('POST', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}/env`, apiKey, { name, value });
-}
-
-// setFunctionEnvBulk writes multiple Worker Secrets in one call. The backend
-// (env.go) loops, calling Cloudflare once per secret, and returns `{set:N}`.
-// The single-secret `setFunctionEnv` above stays the canonical one-off path;
-// this is the bulk variant. The function must already be deployed.
-export async function setFunctionEnvBulk(apiKey: string, orgId: string, fnId: string, env: Record<string, string>): Promise<{ set: number }> {
-  return request('POST', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}/env`, apiKey, { env });
-}
-
-// listFunctionRuns returns recent invocation records, most recent first
-// (Story 4). Capped at 100 server-side.
-export async function listFunctionRuns(apiKey: string, orgId: string, fnId: string): Promise<FunctionRun[]> {
-  return request('GET', `${BASE_URL}/function/orgs/${encodeURIComponent(orgId)}/functions/${encodeURIComponent(fnId)}/runs`, apiKey);
-}

package/src/funds.ts

@@ -1,66 +0,0 @@
-import { MyApiError } from './client';
-
-// The auto-recharge state the backend carries on an `INSUFFICIENT_FUNDS` 402.
-// `in_flight` = a refill was triggered and is on its way (retry); everything
-// else needs a human action, not a retry.
-export type AutoRechargeState = 'in_flight' | 'disabled' | 'capped' | 'no_pm' | 'failed';
-
-// Wallet empty. Matches the unified `INSUFFICIENT_FUNDS` and the legacy
-// `INSUFFICIENT_BALANCE` (still emitted by imagegen's free-tier path until the
-// backend finishes the split — tolerate both).
-export function isInsufficientFunds(err: unknown): err is MyApiError {
-  return err instanceof MyApiError &&
-    (err.code === 'INSUFFICIENT_FUNDS' || err.code === 'INSUFFICIENT_BALANCE');
-}
-
-// Hard account spend ceiling hit (distinct from an empty wallet). Always needs
-// a human — raising/clearing the cap — never a retry or top-up.
-export function isSpendCapExceeded(err: unknown): err is MyApiError {
-  return err instanceof MyApiError && err.code === 'SPEND_CAP_EXCEEDED';
-}
-
-// The auto_recharge state on an INSUFFICIENT_FUNDS error, if the backend set it.
-export function autoRechargeState(err: unknown): AutoRechargeState | undefined {
-  if (!(err instanceof MyApiError)) return undefined;
-  const s = err.body?.auto_recharge;
-  return typeof s === 'string' ? (s as AutoRechargeState) : undefined;
-}
-
-export interface FundsRetryOptions {
-  // Max poll-and-retry attempts on an in-flight refill (default 3).
-  maxRetries?: number;
-  // Injectable sleep (tests pass a no-op; default is real setTimeout).
-  sleep?: (ms: number) => Promise<void>;
-  // Called before each wait — e.g. to log "balance low, refill in flight…".
-  onRetry?: (attempt: number, waitSeconds: number) => void;
-}
-
-const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
-
-// Wrap a billable call so an empty wallet with an auto-recharge IN FLIGHT is
-// polled-and-retried instead of failing — the whole point of the 402 split,
-// so an autonomous agent doesn't escalate to a human for a refill that's
-// already coming. Retries ONLY on `INSUFFICIENT_FUNDS` + `auto_recharge ===
-// 'in_flight'`, sleeping the server-provided `retry_after_seconds` (fallback
-// 5s), up to maxRetries. Every other case — capped / no_pm / failed /
-// disabled, or a `SPEND_CAP_EXCEEDED` hard ceiling — rethrows immediately:
-// those need a human (top up, fix the card, raise the cap), not a retry.
-export async function withFundsRetry<T>(call: () => Promise<T>, opts: FundsRetryOptions = {}): Promise<T> {
-  const maxRetries = opts.maxRetries ?? 3;
-  const sleep = opts.sleep ?? defaultSleep;
-  let attempt = 0;
-  for (;;) {
-    try {
-      return await call();
-    } catch (err) {
-      if (attempt >= maxRetries || !isInsufficientFunds(err) || autoRechargeState(err) !== 'in_flight') {
-        throw err;
-      }
-      attempt++;
-      const hinted = (err as MyApiError).body?.retry_after_seconds;
-      const waitSec = typeof hinted === 'number' && hinted > 0 ? hinted : 5;
-      opts.onRetry?.(attempt, waitSec);
-      await sleep(waitSec * 1000);
-    }
-  }
-}