@tapi-dev/sdk 0.1.10 → 0.1.12

package/README.md

@@ -101,6 +101,48 @@ const completedRun = await tapi.runs.wait(run.id);
 console.log(completedRun.status, completedRun.result);
 ```
 
+## API-Call Triggers
+
+Triggers are scheduled calls to published website APIs. Keep trigger definitions
+in the app repo and sync them after publishing the API catalog:
+
+```ts
+// tapi.config.ts
+export default {
+  triggers: {
+    nightlyBalance: {
+      apiRequest: "schwab.get_balance",
+      schedule: { cron: "0 9 * * MON-FRI" },
+      inputs: { accountId: "main" },
+      runtime: { profileRef: "perm_default" },
+    },
+  },
+};
+```
+
+```bash
+TAPI_API_KEY=tapi_project_key npx tapi triggers sync
+```
+
+`triggers sync` upserts by trigger name for the current `.tapi/project.json`
+project. Schedules support standard five-field cron strings or intervals as
+numbers of seconds / strings like `30s`, `15m`, `2h`, and `1d`.
+
+You can also manage triggers directly:
+
+```ts
+await tapi.triggers.create({
+  name: "nightlyBalance",
+  apiRequest: "schwab.get_balance",
+  schedule: { cron: "0 9 * * MON-FRI" },
+  inputs: { accountId: "main" },
+  runtime: { profileRef: "perm_default" },
+});
+
+await tapi.triggers.fire("act_123");
+await tapi.triggers.disable("act_123");
+```
+
 You can inspect the same input/output contract from the CLI:
 
 ```bash

package/dist/cli.d.ts

@@ -64,8 +64,18 @@ interface StudioCliOptions {
     projectSlug?: string;
     workspaceMode: boolean;
 }
+export interface ServiceStatus {
+    installed: boolean;
+    name?: string;
+    status?: string;
+    pathName?: string;
+    installedVersion?: string;
+}
+type FetchLike = typeof fetch;
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
+export declare function installedServiceVersionFromPathName(pathName: string): string | undefined;
+export declare function serviceNeedsInstall(status: ServiceStatus, manifest: ServiceReleaseManifest): boolean;
 export declare function getDefaultStudioCacheDir(): string;
 export declare function getDefaultServiceCacheDir(): string;
 export declare class CliWideEvent {
@@ -85,5 +95,6 @@ export declare function getStudioExecutableCandidates(): string[];
 export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
 export declare function validateServiceReleaseManifest(input: unknown): ServiceReleaseManifest;
 export declare function compareVersions(left: string, right: string): number;
+export declare function waitForHttpOk(url: string, timeoutMs?: number, intervalMs?: number, fetchImpl?: FetchLike): Promise<void>;
 export declare function findPortableStudioServerExe(releaseDir: string, manifest: StudioReleaseManifest): string | undefined;
 export {};

package/dist/cli.js

@@ -10,7 +10,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { TapiClient } from "./index.js";
 import { loadWorkspace, normalizeProjectValue, writeWorkspaceConfig, } from "./workspace.js";
 const DEFAULT_DOWNLOADS_BASE_URL = "https://d4xaf52nfwiok.cloudfront.net";
@@ -20,6 +20,8 @@ const DEFAULT_FIREBASE_API_KEY = "AIzaSyCDZR8lWyVQcWYfFdNZa4vuL4IWEC0h6gE";
 const DEFAULT_CHANNEL = "pilot";
 const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
 const DEFAULT_INSTALL_AUTH_TIMEOUT_MS = 120_000;
+const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 30_000;
+const PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS = 250;
 const MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
 class StudioInstallApprovalError extends Error {
     code;
@@ -88,6 +90,18 @@ export async function runCli(argv = process.argv.slice(2)) {
         printApisHelp();
         return 1;
     }
+    if (command === "triggers") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+            printTriggersHelp();
+            return 0;
+        }
+        if (subcommand === "sync") {
+            return syncApiTriggers(rest);
+        }
+        console.error(`Unknown triggers command: ${subcommand}`);
+        printTriggersHelp();
+        return 1;
+    }
     if (command !== "studio") {
         console.error(`Unknown command: ${command}`);
         printHelp();
@@ -433,6 +447,298 @@ async function generateApiClient(args) {
         return 1;
     }
 }
+function parseTriggerSyncOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let apiKey = envString("TAPI_API_KEY") || "";
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let configPath = "";
+    const root = workspace?.root || process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--api-key") {
+            apiKey = requireOptionValue(args, ++index, "--api-key");
+            continue;
+        }
+        if (arg.startsWith("--api-key=")) {
+            apiKey = arg.slice("--api-key=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--config") {
+            configPath = requireOptionValue(args, ++index, "--config");
+            continue;
+        }
+        if (arg.startsWith("--config=")) {
+            configPath = arg.slice("--config=".length);
+            continue;
+        }
+        throw new Error(`Unknown triggers option: ${arg}`);
+    }
+    if (!apiKey) {
+        throw new Error("triggers sync requires --api-key or TAPI_API_KEY.");
+    }
+    if (!projectId) {
+        throw new Error("triggers sync requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        apiKey,
+        projectId,
+        configPath: configPath ? resolve(root, configPath) : defaultTriggerConfigPath(root),
+    };
+}
+async function syncApiTriggers(args) {
+    try {
+        const options = parseTriggerSyncOptions(args);
+        const triggers = await readApiTriggerConfig(options.configPath);
+        if (triggers.length === 0) {
+            throw new Error(`No Tapi API triggers found in ${options.configPath}.`);
+        }
+        const client = new TapiClient({
+            baseUrl: options.apiBaseUrl,
+            apiKey: options.apiKey,
+            projectId: options.projectId,
+        });
+        for (const trigger of triggers) {
+            await client.triggers.create(trigger);
+        }
+        console.log(`Synced ${triggers.length} Tapi API trigger(s) from ${options.configPath}.`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+function defaultTriggerConfigPath(root) {
+    for (const name of ["tapi.config.ts", "tapi.config.mjs", "tapi.config.js", "tapi.config.cjs", "tapi.config.json"]) {
+        const path = join(root, name);
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    return join(root, "tapi.config.json");
+}
+async function readApiTriggerConfig(configPath) {
+    if (!existsSync(configPath)) {
+        throw new Error(`Tapi trigger config not found at ${configPath}. Create tapi.config.json or pass --config.`);
+    }
+    const payload = await loadTriggerConfigPayload(configPath);
+    return normalizeTriggerConfig(payload, configPath);
+}
+async function loadTriggerConfigPayload(configPath) {
+    if (configPath.endsWith(".json")) {
+        return JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    if (configPath.endsWith(".ts")) {
+        return evaluateTypeScriptTriggerConfig(configPath);
+    }
+    if (configPath.endsWith(".js") || configPath.endsWith(".mjs") || configPath.endsWith(".cjs")) {
+        const moduleUrl = pathToFileURL(configPath).href;
+        const module = await import(moduleUrl);
+        return module.default ?? module;
+    }
+    throw new Error("Tapi trigger config must be a .json, .js, .mjs, .cjs, or simple .ts file.");
+}
+function evaluateTypeScriptTriggerConfig(configPath) {
+    let source = readFileSync(configPath, "utf8");
+    source = source.replace(/^\s*import\s+type\s+[\s\S]*?;\s*$/gm, "");
+    source = source.replace(/^\s*import\s+[\s\S]*?;\s*$/gm, "");
+    const marker = "export default";
+    const markerIndex = source.indexOf(marker);
+    if (markerIndex < 0) {
+        throw new Error("tapi.config.ts must use `export default { ... }`.");
+    }
+    let expression = source.slice(markerIndex + marker.length).trim();
+    if (expression.endsWith(";")) {
+        expression = expression.slice(0, -1).trim();
+    }
+    expression = expression.replace(/\s+satisfies\s+[\s\S]+$/m, "").trim();
+    expression = expression.replace(/\s+as\s+const\s*$/m, "").trim();
+    try {
+        return Function("process", `"use strict"; return (${expression});`)(process);
+    }
+    catch (error) {
+        throw new Error(`Could not evaluate ${configPath}: ${formatError(error)}. Use a simple export default object or switch to tapi.config.js/json.`);
+    }
+}
+function normalizeTriggerConfig(payload, configPath) {
+    const rawTriggers = isRecord(payload) && "triggers" in payload ? payload.triggers : payload;
+    if (Array.isArray(rawTriggers)) {
+        return rawTriggers.map((entry, index) => normalizeTriggerEntry(entry, index, configPath));
+    }
+    if (isRecord(rawTriggers)) {
+        return Object.entries(rawTriggers).map(([name, entry], index) => {
+            if (!isRecord(entry)) {
+                throw new Error(`Trigger '${name}' in ${configPath} must be an object.`);
+            }
+            return normalizeTriggerEntry({ name, ...entry }, index, configPath);
+        });
+    }
+    throw new Error(`Tapi trigger config at ${configPath} must contain a triggers array or object.`);
+}
+function normalizeTriggerEntry(entry, index, configPath) {
+    if (!isRecord(entry)) {
+        throw new Error(`Trigger #${index + 1} in ${configPath} must be an object.`);
+    }
+    const name = stringField(entry.name, `Trigger #${index + 1} name`);
+    const apiRequest = optionalStringField(entry.apiRequest, "apiRequest") ??
+        optionalStringField(entry.api, "api") ??
+        apiRequestFromParts(entry.apiName, entry.requestKey);
+    if (!apiRequest) {
+        throw new Error(`Trigger '${name}' requires apiRequest, api, or apiName/requestKey.`);
+    }
+    if (!apiRequest.includes(".")) {
+        throw new Error(`Trigger '${name}' apiRequest must be formatted as '<apiName>.<requestKey>'.`);
+    }
+    const schedule = normalizeTriggerSchedule(entry.schedule, entry.interval, name);
+    const request = {
+        name,
+        apiRequest,
+        ...(entry.enabled === undefined ? {} : { enabled: booleanField(entry.enabled, `Trigger '${name}' enabled`) }),
+        ...(schedule ? { schedule } : {}),
+        ...(entry.inputs === undefined ? {} : { inputs: recordField(entry.inputs, `Trigger '${name}' inputs`) }),
+        ...(entry.runtime === undefined ? {} : { runtime: recordField(entry.runtime, `Trigger '${name}' runtime`) }),
+        ...(entry.runnerId === undefined ? {} : { runnerId: stringField(entry.runnerId, `Trigger '${name}' runnerId`) }),
+        ...(entry.priority === undefined ? {} : { priority: numberField(entry.priority, `Trigger '${name}' priority`) }),
+        ...(entry.site === undefined ? {} : { site: stringField(entry.site, `Trigger '${name}' site`) }),
+    };
+    return request;
+}
+function normalizeTriggerSchedule(scheduleValue, intervalValue, name) {
+    if (scheduleValue === undefined && intervalValue === undefined) {
+        return undefined;
+    }
+    if (typeof scheduleValue === "string" && looksLikeCron(scheduleValue)) {
+        return { cron: scheduleValue.trim() };
+    }
+    if (typeof scheduleValue === "number" || typeof scheduleValue === "string") {
+        return { intervalSeconds: parseDurationSeconds(scheduleValue, `Trigger '${name}' schedule`) };
+    }
+    if (scheduleValue !== undefined && !isRecord(scheduleValue)) {
+        throw new Error(`Trigger '${name}' schedule must be an object, number, or duration string.`);
+    }
+    const schedule = scheduleValue === undefined ? {} : { ...scheduleValue };
+    if (intervalValue !== undefined) {
+        if ("cron" in schedule) {
+            throw new Error(`Trigger '${name}' cannot define both cron and interval.`);
+        }
+        schedule.intervalSeconds = parseDurationSeconds(intervalValue, `Trigger '${name}' interval`);
+    }
+    else if ("interval" in schedule) {
+        if ("cron" in schedule) {
+            throw new Error(`Trigger '${name}' cannot define both cron and interval.`);
+        }
+        schedule.intervalSeconds = parseDurationSeconds(schedule.interval, `Trigger '${name}' schedule.interval`);
+        delete schedule.interval;
+    }
+    else if ("interval_seconds" in schedule) {
+        if ("cron" in schedule) {
+            throw new Error(`Trigger '${name}' cannot define both cron and interval_seconds.`);
+        }
+        schedule.intervalSeconds = parseDurationSeconds(schedule.interval_seconds, `Trigger '${name}' schedule.interval_seconds`);
+        delete schedule.interval_seconds;
+    }
+    else if ("intervalSeconds" in schedule) {
+        if ("cron" in schedule) {
+            throw new Error(`Trigger '${name}' cannot define both cron and intervalSeconds.`);
+        }
+        schedule.intervalSeconds = parseDurationSeconds(schedule.intervalSeconds, `Trigger '${name}' schedule.intervalSeconds`);
+    }
+    else if ("cron" in schedule) {
+        schedule.cron = stringField(schedule.cron, `Trigger '${name}' schedule.cron`);
+    }
+    if (!("intervalSeconds" in schedule) && !("cron" in schedule)) {
+        throw new Error(`Trigger '${name}' schedule requires intervalSeconds, interval, or cron.`);
+    }
+    return schedule;
+}
+function looksLikeCron(value) {
+    return value.trim().split(/\s+/).length === 5;
+}
+function parseDurationSeconds(value, fieldName) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new Error(`${fieldName} must be a positive number of seconds.`);
+        }
+        return Math.round(value);
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${fieldName} must be a number of seconds or a duration string like '15m'.`);
+    }
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days)?$/i);
+    if (!match) {
+        throw new Error(`${fieldName} must be a duration like '30s', '15m', '2h', or '1d'.`);
+    }
+    const amount = Number(match[1]);
+    const unit = (match[2] || "s").toLowerCase();
+    const multiplier = unit.startsWith("m") ? 60 :
+        unit.startsWith("h") ? 3600 :
+            unit.startsWith("d") ? 86400 :
+                1;
+    const seconds = Math.round(amount * multiplier);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new Error(`${fieldName} must be greater than zero seconds.`);
+    }
+    return seconds;
+}
+function apiRequestFromParts(apiName, requestKey) {
+    const api = optionalStringField(apiName, "apiName");
+    const request = optionalStringField(requestKey, "requestKey");
+    return api && request ? `${api}.${request}` : undefined;
+}
+function stringField(value, fieldName) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${fieldName} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function optionalStringField(value, fieldName) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    return stringField(value, fieldName);
+}
+function booleanField(value, fieldName) {
+    if (typeof value !== "boolean") {
+        throw new Error(`${fieldName} must be true or false.`);
+    }
+    return value;
+}
+function numberField(value, fieldName) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${fieldName} must be a finite number.`);
+    }
+    return value;
+}
+function recordField(value, fieldName) {
+    if (!isRecord(value)) {
+        throw new Error(`${fieldName} must be an object.`);
+    }
+    return value;
+}
 async function fetchApiCatalog(options) {
     const client = new TapiClient({
         baseUrl: options.apiBaseUrl,
@@ -620,7 +926,7 @@ async function repairService(options) {
 }
 function servicePowerShell(action) {
     const serviceName = "tapi-service";
-    const status = `$svc = Get-Service -Name '${serviceName}' -ErrorAction SilentlyContinue; if ($null -eq $svc) { [pscustomobject]@{ installed = $false; name = '${serviceName}'; status = 'not_installed' } | ConvertTo-Json -Compress; exit 0 }; [pscustomobject]@{ installed = $true; name = $svc.Name; status = $svc.Status.ToString() } | ConvertTo-Json -Compress`;
+    const status = `$svc = Get-Service -Name '${serviceName}' -ErrorAction SilentlyContinue; if ($null -eq $svc) { [pscustomobject]@{ installed = $false; name = '${serviceName}'; status = 'not_installed'; pathName = '' } | ConvertTo-Json -Compress; exit 0 }; $cim = Get-CimInstance Win32_Service -Filter "Name='${serviceName}'" -ErrorAction SilentlyContinue; $pathName = if ($null -ne $cim) { [string]$cim.PathName } else { '' }; [pscustomobject]@{ installed = $true; name = $svc.Name; status = $svc.Status.ToString(); pathName = $pathName } | ConvertTo-Json -Compress`;
     if (action === "status") {
         return status;
     }
@@ -649,6 +955,8 @@ async function getServiceStatus() {
             installed: Boolean(payload.installed),
             name: typeof payload.name === "string" ? payload.name : "tapi-service",
             status: typeof payload.status === "string" ? payload.status : "unknown",
+            pathName: typeof payload.pathName === "string" ? payload.pathName : "",
+            installedVersion: installedServiceVersionFromPathName(typeof payload.pathName === "string" ? payload.pathName : ""),
         };
     }
     catch {
@@ -665,6 +973,16 @@ async function ensureServiceReadyForStudio(options) {
         }
         return;
     }
+    const manifest = await fetchServiceManifestForEnsure(options);
+    if (manifest && serviceNeedsInstall(status, manifest)) {
+        const current = status.installedVersion || "unknown";
+        console.log(`Updating Tapi Service from ${current} to ${manifest.version}...`);
+        const code = await installService(options);
+        if (code !== 0) {
+            throw new Error("Tapi Service update failed.");
+        }
+        return;
+    }
     if (status.status !== "Running") {
         console.log("Starting Tapi Service...");
         const output = await runProcessCapture("powershell.exe", [
@@ -679,6 +997,75 @@ async function ensureServiceReadyForStudio(options) {
         }
     }
 }
+async function fetchServiceManifestForEnsure(options) {
+    const event = await createCliWideEvent("tapi_cli.service_ensure", {
+        sdk_version: sdkVersion,
+        options: installEventOptions(options),
+    });
+    try {
+        let installToken = options.installToken?.trim();
+        if (!installToken) {
+            await event.phase("auth.install_token.request.start", {
+                apiBaseUrl: options.apiBaseUrl,
+                channel: options.channel,
+            });
+            installToken = await obtainStudioInstallToken(options, event);
+            await event.phase("auth.install_token.request.success", {
+                apiBaseUrl: options.apiBaseUrl,
+                channel: options.channel,
+            });
+        }
+        await event.phase("service_manifest.fetch.start", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        const manifest = await fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken);
+        ensureCompatibleServiceManifest(manifest);
+        await event.finish(true, {
+            manifest: serviceManifestEventSummary(manifest),
+        });
+        return manifest;
+    }
+    catch (error) {
+        await event.finish(false, {
+            error: errorDetails(error),
+        });
+        if (isProtectedServiceManifestAuthError(error)) {
+            throw error;
+        }
+        console.warn(`Could not check for Tapi Service updates: ${formatError(error)}`);
+        return null;
+    }
+}
+function isProtectedServiceManifestAuthError(error) {
+    const message = formatError(error);
+    return (message.includes("Failed to fetch protected Tapi Service manifest: HTTP 401")
+        || message.includes("Failed to fetch protected Tapi Service manifest: HTTP 403")
+        || message.includes("Worker bootstrap secret required"));
+}
+export function installedServiceVersionFromPathName(pathName) {
+    const normalized = String(pathName || "").replace(/\\/g, "/");
+    const parts = normalized
+        .split("/")
+        .map((part) => part.trim().replace(/^"+|"+$/g, ""))
+        .filter(Boolean);
+    const releasesIndex = parts.findIndex((part) => part.toLowerCase() === "releases");
+    if (releasesIndex < 0 || releasesIndex + 1 >= parts.length) {
+        return undefined;
+    }
+    const version = parts[releasesIndex + 1]?.replace(/^"+|"+$/g, "").trim();
+    return version || undefined;
+}
+export function serviceNeedsInstall(status, manifest) {
+    if (!status.installed) {
+        return true;
+    }
+    const installedVersion = status.installedVersion || installedServiceVersionFromPathName(status.pathName || "");
+    if (!installedVersion) {
+        return true;
+    }
+    return installedVersion !== manifest.version;
+}
 async function installService(options) {
     const event = await createCliWideEvent("tapi_cli.service_install", {
         sdk_version: sdkVersion,
@@ -1468,9 +1855,36 @@ async function launchPortableStudioServer(exePath, options) {
     });
     child.unref();
     const url = `http://${host}:${port}`;
+    await waitForHttpOk(`${url}/healthz`, PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS);
     openBrowser(url);
     console.log(`Opened Tapi Studio: ${url}`);
 }
+export async function waitForHttpOk(url, timeoutMs = PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, intervalMs = PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS, fetchImpl = fetch) {
+    const startedAt = performance.now();
+    let lastError = "";
+    while (performance.now() - startedAt < timeoutMs) {
+        try {
+            const response = await fetchImpl(url, {
+                headers: { Accept: "application/json" },
+            });
+            if (response.ok) {
+                return;
+            }
+            lastError = `HTTP ${response.status}`;
+        }
+        catch (error) {
+            lastError = formatError(error);
+        }
+        await delay(intervalMs);
+    }
+    const suffix = lastError ? ` Last error: ${lastError}.` : "";
+    throw new Error(`Tapi Studio server did not become ready at ${url} within ${Math.ceil(timeoutMs / 1000)}s.${suffix}`);
+}
+function delay(ms) {
+    return new Promise((resolvePromise) => {
+        setTimeout(resolvePromise, Math.max(0, ms));
+    });
+}
 async function chooseStudioPort(preferred = 18766) {
     for (let port = preferred; port < preferred + 25; port += 1) {
         if (await isPortAvailable(port)) {
@@ -2085,6 +2499,7 @@ Usage:
   tapi apis describe <namespace.operation>
   tapi apis sync
   tapi apis generate
+  tapi triggers sync
   tapi publish
   tapi service status
   tapi doctor
@@ -2099,6 +2514,7 @@ Commands:
   apis describe   Print a generated website API input/output contract
   apis sync       Save the published API catalog to .tapi/generated
   apis generate   Generate a TypeScript runtime wrapper from the catalog
+  triggers sync   Upsert API-call triggers from tapi.config
   publish         Upload local .tapi API drafts and publish ready requests
   service         Inspect or control the local Tapi Windows service
   doctor          Alias for studio doctor
@@ -2121,6 +2537,32 @@ Options:
   --out <path>           Generated TypeScript output path
 `);
 }
+function printTriggersHelp() {
+    console.log(`Tapi API trigger commands
+
+Usage:
+  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+Options:
+  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+
+Config:
+  export default {
+    triggers: {
+      nightlyBalance: {
+        apiRequest: "schwab.get_balance",
+        interval: "1h",
+        inputs: { accountId: "main" },
+        runtime: { profileRef: "perm_default" },
+      },
+    },
+  };
+`);
+}
 function printStudioHelp() {
     console.log(`Tapi Studio commands
 

package/dist/client.d.ts

@@ -7,5 +7,7 @@ export declare class HttpClient {
     constructor(options: TapiClientOptions);
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
     private request;
 }

package/dist/client.js

@@ -16,6 +16,12 @@ export class HttpClient {
     async post(path, body) {
         return this.request("POST", path, body);
     }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
     async request(method, path, body) {
         const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { CatalogResource } from "./catalog.js";
 import { RunnersResource } from "./runners.js";
 import { RunsResource } from "./runs.js";
 import { RuntimeResource } from "./runtime.js";
+import { TriggersResource } from "./triggers.js";
 import type { TapiClientOptions } from "./types.js";
 import { WebsiteApisResource } from "./website-apis.js";
 export declare class TapiClient {
@@ -11,6 +12,7 @@ export declare class TapiClient {
     readonly runners: RunnersResource;
     readonly runs: RunsResource;
     readonly runtime: RuntimeResource;
+    readonly triggers: TriggersResource;
     readonly websiteApis: WebsiteApisResource;
     constructor(options: TapiClientOptions);
 }

package/dist/index.js

@@ -4,6 +4,7 @@ import { CatalogResource } from "./catalog.js";
 import { RunnersResource } from "./runners.js";
 import { RunsResource } from "./runs.js";
 import { RuntimeResource } from "./runtime.js";
+import { TriggersResource } from "./triggers.js";
 import { WebsiteApisResource } from "./website-apis.js";
 export class TapiClient {
     catalog;
@@ -11,6 +12,7 @@ export class TapiClient {
     runners;
     runs;
     runtime;
+    triggers;
     websiteApis;
     constructor(options) {
         const http = new HttpClient(options);
@@ -19,6 +21,7 @@ export class TapiClient {
         this.runners = new RunnersResource(http);
         this.runs = new RunsResource(http);
         this.runtime = new RuntimeResource(http, options);
+        this.triggers = new TriggersResource(http);
         this.websiteApis = new WebsiteApisResource(http);
     }
 }

package/dist/triggers.d.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from "./client.js";
+import type { WebsiteApiTrigger, WebsiteApiTriggerCreateRequest, WebsiteApiTriggerList, WebsiteApiTriggerRunResult, WebsiteApiTriggerUpdateRequest } from "./types.js";
+export declare class TriggersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<WebsiteApiTriggerList>;
+    create(request: WebsiteApiTriggerCreateRequest): Promise<WebsiteApiTrigger>;
+    get(triggerId: string): Promise<WebsiteApiTrigger>;
+    update(triggerId: string, request: WebsiteApiTriggerUpdateRequest): Promise<WebsiteApiTrigger>;
+    enable(triggerId: string): Promise<WebsiteApiTrigger>;
+    disable(triggerId: string): Promise<WebsiteApiTrigger>;
+    delete(triggerId: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    fire(triggerId: string): Promise<WebsiteApiTriggerRunResult>;
+}

package/dist/triggers.js

@@ -0,0 +1,30 @@
+export class TriggersResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list() {
+        return this.http.get("/api/sdk/v1/website-api-triggers");
+    }
+    create(request) {
+        return this.http.post("/api/sdk/v1/website-api-triggers", request);
+    }
+    get(triggerId) {
+        return this.http.get(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`);
+    }
+    update(triggerId, request) {
+        return this.http.patch(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`, request);
+    }
+    enable(triggerId) {
+        return this.update(triggerId, { enabled: true });
+    }
+    disable(triggerId) {
+        return this.update(triggerId, { enabled: false });
+    }
+    delete(triggerId) {
+        return this.http.delete(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`);
+    }
+    fire(triggerId) {
+        return this.http.post(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}/run`);
+    }
+}

package/dist/types.d.ts

@@ -162,6 +162,54 @@ export interface WebsiteApiOperation {
     outputSchema?: Record<string, unknown>;
     [key: string]: unknown;
 }
+export interface WebsiteApiTriggerSchedule {
+    intervalSeconds?: number;
+    cron?: string;
+    [key: string]: unknown;
+}
+export interface WebsiteApiTriggerCreateRequest {
+    name: string;
+    apiRequest: string;
+    enabled?: boolean;
+    schedule?: WebsiteApiTriggerSchedule;
+    inputs?: Record<string, unknown>;
+    runtime?: RuntimeRunOptions;
+    runnerId?: string;
+    priority?: number;
+    site?: string;
+}
+export interface WebsiteApiTriggerUpdateRequest {
+    enabled: boolean;
+}
+export interface WebsiteApiTrigger {
+    id: string;
+    name: string;
+    apiRequest: string;
+    apiName: string;
+    requestKey: string;
+    site?: string;
+    enabled: boolean;
+    schedule?: WebsiteApiTriggerSchedule | Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    runtime?: RuntimeRunOptions | Record<string, unknown>;
+    runnerId?: string;
+    priority?: number;
+    lastRun?: TapiRun | Record<string, unknown> | null;
+    lastError?: string;
+    lastFiredAt?: string | null;
+    nextFireAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface WebsiteApiTriggerList {
+    triggers: WebsiteApiTrigger[];
+}
+export interface WebsiteApiTriggerRunResult {
+    success: boolean;
+    trigger: WebsiteApiTrigger;
+    run: TapiRun | Record<string, unknown>;
+}
 export interface TapiRun {
     id: string;
     status: RunStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",