@myapihq/sdk 1.2.8 → 1.3.0

package/src/services.ts

@@ -20,7 +20,8 @@ export type ServiceCategory =
   | 'capture'   // inbound: webhook, pixel
   | 'data'      // read/filter the data layer: people, company, audience, crm
   | 'store'     // persist bytes/JSON: storage, database
-  | 'compute'   // run code or inference: llm, workflow
+  | 'compute'   // run code or inference: llm, fn
+  | 'orchestrate' // control flow: workflow, queue, task
   | 'identity'  // auth/billing/account: hq
   | 'infra';    // platform glue: domain
 
@@ -65,16 +66,16 @@ export const SERVICES: readonly ServiceMeta[] = [
 
   // ── send ────────────────────────────────────────────────────────────
   {
-    // Customer-facing email surface (mailboxes, campaigns, templates,
-    // warmup) is gated pre-launch — 503 SERVICE_NOT_LAUNCHED. Sibling
-    // `my-email-verify-api` stays GA and remains the discoverable entry
-    // point for the email primitive today.
+    // Customer-facing email surface — mailboxes, campaigns, templates,
+    // warmup. Launched 2026-05-17: the backend lifted the pre-launch gate
+    // (the [disabled, pre-launch] / 503 SERVICE_NOT_LAUNCHED state is gone).
+    // Sibling `my-email-verify-api` is the sync single-address verifier.
     module: 'email',
     skill: 'my-email-api',
     domain: 'myemailapi.com',
     description: 'Send transactional and bulk email from your own domain. Mailboxes, AI templates, drip campaigns, and warmup.',
     category: 'send',
-    status: 'preview',
+    status: 'ga',
     keywords: k('email', 'transactional', 'campaign', 'smtp'),
   },
   {
@@ -201,15 +202,6 @@ export const SERVICES: readonly ServiceMeta[] = [
   },
 
   // ── compute ─────────────────────────────────────────────────────────
-  {
-    module: 'workflow',
-    skill: 'my-workflow-api',
-    domain: 'myworkflowapi.com',
-    description: 'React to inbound webhooks with step chains: send email, post to Slack, call HTTP URLs.',
-    category: 'compute',
-    status: 'ga',
-    keywords: k('workflow', 'automation', 'orchestration'),
-  },
   {
     module: 'llm',
     skill: 'my-llm-api',
@@ -266,4 +258,54 @@ export const SERVICES: readonly ServiceMeta[] = [
     status: 'preview',
     keywords: k('container', 'cloud-run', 'service', 'worker', 'job'),
   },
+  {
+    // CLI top-level command + SDK namespace are both `git`; skill directory
+    // is `my-git-api`. A stateless git-over-HTTP surface (go-git engine;
+    // objects in GCS, refs in Postgres) — repos, commits, branches, history.
+    module: 'git',
+    skill: 'my-git-api',
+    domain: 'mygitapi.com',
+    description: 'Hosted git repositories over HTTP — create repos, commit files, manage branches and tags, read trees, blobs, history, and diffs. No local clone required.',
+    category: 'store',
+    status: 'preview',
+    keywords: k('git', 'repository', 'version-control', 'commit', 'scm'),
+  },
+
+  // ── orchestrate ─────────────────────────────────────────────────────
+  // Control flow, not actions. workflow = event→action, queue = durable
+  // async machine work, task = work that needs an agent/human decision.
+  // See docs/orchestration-decision-guide.md.
+  {
+    module: 'workflow',
+    skill: 'my-workflow-api',
+    domain: 'myworkflowapi.com',
+    description: 'React to inbound webhooks with step chains: send email, post to Slack, call HTTP URLs.',
+    category: 'orchestrate',
+    status: 'ga',
+    keywords: k('workflow', 'automation', 'orchestration'),
+  },
+  {
+    // CLI top-level command + SDK namespace are both `queue`; skill
+    // directory is `my-queue-api`. A durable HTTP-consumer job queue —
+    // retry/backoff, concurrency caps, dependency DAG.
+    module: 'queue',
+    skill: 'my-queue-api',
+    domain: 'myqueueapi.com',
+    description: 'Durable job queue — enqueue work and have it retried against your HTTP consumer, with concurrency caps and a dependency DAG.',
+    category: 'orchestrate',
+    status: 'preview',
+    keywords: k('queue', 'job-queue', 'background-jobs', 'retry', 'async'),
+  },
+  {
+    // CLI top-level command + SDK namespace are both `task`; skill
+    // directory is `my-task-api`. The agent-task queue — the agent-loop
+    // hot path: file, claim under a lease, resolve.
+    module: 'task',
+    skill: 'my-task-api',
+    domain: 'mytaskapi.com',
+    description: 'Agent-task queue — file units of work, rank them, claim under a lease, then resolve, fail, or cancel. The agent-loop hot path.',
+    category: 'orchestrate',
+    status: 'preview',
+    keywords: k('task', 'task-queue', 'agent-loop', 'work-queue', 'lease'),
+  },
 ] as const;

package/src/task.ts

@@ -0,0 +1,198 @@
+import { request } from './client';
+import { TASK_BASE as BASE_URL } from './config';
+import type { Exposes } from './exposes';
+
+// Backend: my-task-api per myapi-hq/internal/routes/task/. An agent-task
+// queue — the agent-loop hot path. Tasks are created, ranked by score,
+// claimed under a lease, then resolved/failed/cancelled. A task with
+// unresolved depends_on starts blocked; lease expiry auto-reverts a claimed
+// task to open.
+export const EXPOSES: Exposes = [
+  'POST /task/orgs/{org_id}/tasks',
+  'GET /task/orgs/{org_id}/tasks',
+  'GET /task/orgs/{org_id}/tasks/{id}',
+  'DELETE /task/orgs/{org_id}/tasks/{id}',
+  'GET /task/orgs/{org_id}/tasks/{id}/body',
+  'POST /task/orgs/{org_id}/tasks/{id}/claim',
+  'POST /task/orgs/{org_id}/tasks/{id}/extend',
+  'POST /task/orgs/{org_id}/tasks/{id}/fail',
+  'POST /task/orgs/{org_id}/tasks/{id}/resolve',
+];
+
+export type TaskStatus = 'open' | 'claimed' | 'blocked' | 'resolved' | 'failed' | 'cancelled';
+
+export type TaskImportance = 'low' | 'normal' | 'high' | 'critical';
+
+// Event matcher: a matching platform_events delivery auto-resolves the task.
+export interface ResolveOn {
+  event_type: string;
+  field?: string;
+  value?: string;
+}
+
+// The projected list row — list deliberately returns only this triage-sized
+// shape, not the full task. Read the body tier separately via getTaskBody.
+export interface TaskRef {
+  id: string;
+  description: string;
+  score: number;
+}
+
+// Full task object. `claim` and `extend` return this — lease state is read
+// off `lease_expires_at` / `claimed_by`, not a separate lease object.
+export interface Task {
+  id: string;
+  org_id: string;
+  description: string;
+  status: TaskStatus;
+  importance: TaskImportance;
+  score: number;
+  tags: string[];
+  source: string;
+  depends_on: string[];
+  payload_url: string;
+  assignee?: string;
+  resolve_on?: ResolveOn;
+  dedup_key?: string;
+  claimed_by?: string;
+  lease_expires_at?: string;
+  due_at?: string;
+  fail_reason?: string;
+  resolved_at?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+// Backlog health from the list envelope's meta — the agent's "am I keeping
+// up" signal. `shown` is how many rows came back; `total_open` is the whole
+// open queue depth.
+export interface TaskListMeta {
+  shown: number;
+  total_open: number;
+}
+
+export interface TaskListResult {
+  tasks: TaskRef[];
+  meta: TaskListMeta;
+}
+
+export interface CreateTaskOptions {
+  description: string;
+  // Full Markdown context. Staged to the body tier; read once via getTaskBody.
+  body?: string;
+  importance?: TaskImportance;
+  dueAt?: string;
+  assignee?: string;
+  tags?: string[];
+  // Task ids this task waits on. Immutable — declared only at creation.
+  // Same shape as queue.enqueue's depends_on.
+  dependsOn?: string[];
+  dedupKey?: string;
+  resolveOn?: ResolveOn;
+  source?: string;
+}
+
+export interface ListTaskOptions {
+  status?: string;
+  tag?: string;
+  importance?: string;
+  assignee?: string;
+  source?: string;
+  limit?: number;
+}
+
+function tasksBase(orgId: string): string {
+  return `${BASE_URL}/task/orgs/${encodeURIComponent(orgId)}/tasks`;
+}
+
+function taskBase(orgId: string, id: string): string {
+  return `${tasksBase(orgId)}/${encodeURIComponent(id)}`;
+}
+
+// createTask is idempotent on (org_id, dedup_key). A task with unresolved
+// depends_on starts blocked; one with an assignee emails them a magic link.
+export async function createTask(apiKey: string, orgId: string, opts: CreateTaskOptions): Promise<Task> {
+  const body: Record<string, unknown> = { description: opts.description };
+  if (opts.body !== undefined) body.body = opts.body;
+  if (opts.importance !== undefined) body.importance = opts.importance;
+  if (opts.dueAt !== undefined) body.due_at = opts.dueAt;
+  if (opts.assignee !== undefined) body.assignee = opts.assignee;
+  if (opts.tags !== undefined) body.tags = opts.tags;
+  if (opts.dependsOn !== undefined) body.depends_on = opts.dependsOn;
+  if (opts.dedupKey !== undefined) body.dedup_key = opts.dedupKey;
+  if (opts.resolveOn !== undefined) body.resolve_on = opts.resolveOn;
+  if (opts.source !== undefined) body.source = opts.source;
+  return request('POST', tasksBase(orgId), apiKey, body);
+}
+
+// listTasks returns the ranked open queue (projected to TaskRef) plus the
+// backlog counts. Default: top 20 open tasks by score. The backend nests
+// {shown, total_open} inside the response `data.meta` (not the envelope meta).
+export async function listTasks(apiKey: string, orgId: string, opts: ListTaskOptions = {}): Promise<TaskListResult> {
+  const q = new URLSearchParams();
+  if (opts.status) q.set('status', opts.status);
+  if (opts.tag) q.set('tag', opts.tag);
+  if (opts.importance) q.set('importance', opts.importance);
+  if (opts.assignee) q.set('assignee', opts.assignee);
+  if (opts.source) q.set('source', opts.source);
+  if (opts.limit !== undefined) q.set('limit', String(opts.limit));
+  const qs = q.toString();
+  const res = await request<{ tasks?: TaskRef[]; meta?: Partial<TaskListMeta> }>(
+    'GET', `${tasksBase(orgId)}${qs ? `?${qs}` : ''}`, apiKey,
+  );
+  const tasks = res?.tasks ?? [];
+  const m = res?.meta ?? {};
+  return {
+    tasks,
+    meta: {
+      shown: typeof m.shown === 'number' ? m.shown : tasks.length,
+      total_open: typeof m.total_open === 'number' ? m.total_open : tasks.length,
+    },
+  };
+}
+
+// getTask returns the full task object. It deliberately does NOT fetch the
+// Markdown body tier — call getTaskBody for that, once, on commit.
+export async function getTask(apiKey: string, orgId: string, id: string): Promise<Task> {
+  return request('GET', taskBase(orgId, id), apiKey);
+}
+
+// getTaskBody fetches the body tier — the full Markdown context. Separate
+// call by design: it keeps the list/get path token-cheap. The endpoint
+// returns { task_id, body }.
+export async function getTaskBody(apiKey: string, orgId: string, id: string): Promise<string> {
+  const res = await request<{ task_id: string; body: string }>('GET', `${taskBase(orgId, id)}/body`, apiKey);
+  return res?.body ?? '';
+}
+
+// claimTask takes an atomic lease (default 10 min) and returns the full
+// updated task — lease state is on `lease_expires_at` / `claimed_by`.
+export async function claimTask(apiKey: string, orgId: string, id: string, opts: { leaseSeconds?: number; worker?: string } = {}): Promise<Task> {
+  const body: Record<string, unknown> = {};
+  if (opts.leaseSeconds !== undefined) body.lease_seconds = opts.leaseSeconds;
+  if (opts.worker !== undefined) body.worker = opts.worker;
+  return request('POST', `${taskBase(orgId, id)}/claim`, apiKey, body);
+}
+
+// extendTask is a heartbeat for long work — extends a live claim.
+export async function extendTask(apiKey: string, orgId: string, id: string, opts: { leaseSeconds?: number } = {}): Promise<Task> {
+  const body: Record<string, unknown> = {};
+  if (opts.leaseSeconds !== undefined) body.lease_seconds = opts.leaseSeconds;
+  return request('POST', `${taskBase(orgId, id)}/extend`, apiKey, body);
+}
+
+// resolveTask resolves a task (terminal) — unblocks any dependents.
+export async function resolveTask(apiKey: string, orgId: string, id: string): Promise<Task> {
+  return request('POST', `${taskBase(orgId, id)}/resolve`, apiKey, {});
+}
+
+// failTask fails a task (terminal, with a reason). Does not auto-retry;
+// dependents that can never proceed are auto-failed.
+export async function failTask(apiKey: string, orgId: string, id: string, reason: string): Promise<Task> {
+  return request('POST', `${taskBase(orgId, id)}/fail`, apiKey, { reason });
+}
+
+// cancelTask cancels a task (terminal, distinct from fail).
+export async function cancelTask(apiKey: string, orgId: string, id: string): Promise<void> {
+  return request('DELETE', taskBase(orgId, id), apiKey);
+}

package/src/workflow.ts

@@ -33,7 +33,13 @@ export type WorkflowStep =
   // Backend (2026-05-15): `http_request` step is now accepted (alias: `http`).
   // POSTs (or other method) to `url` with the inbound payload; supports
   // template substitution in url/body the same way email steps do.
-  | { type: 'http_request' | 'http'; url: string; method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'; body?: string; headers?: Record<string, string> };
+  | { type: 'http_request' | 'http'; url: string; method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'; body?: string; headers?: Record<string, string> }
+  // `enqueue_job` (alias: `enqueue`) hands durable work to my-queue-api —
+  // the step enqueues a job on `queue` carrying `payload` (template
+  // substitution supported, same as email/http steps). The workflow stays
+  // the trigger layer; the queue owns retry/durability. Backend: pending —
+  // see docs/cross-repo-prompts/backend-orchestration-composition.md.
+  | { type: 'enqueue_job' | 'enqueue'; queue: string; payload?: string; dedup_key?: string; delay_seconds?: number };
 
 export interface Workflow {
   id: string;