@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/routes/schedules.ts

@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import type { Cursor, TenantId, TriggerId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type {
+  CronTriggerRecord,
+  RegisterCronTriggerInput,
+  TriggerRegistryBinding,
+  UpdateCronTriggerInput,
+} from '../trigger-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Schedules — cron-kind triggers.
+ *
+ * Seven routes, all soft-delete-shaped per framework convention:
+ *   - POST   /v1/schedules                 (register)
+ *   - GET    /v1/schedules                 (list, cursor-paginated)
+ *   - GET    /v1/schedules/:triggerId      (get)
+ *   - PATCH  /v1/schedules/:triggerId      (update cron/label/flowVersion)
+ *   - POST   /v1/schedules/:triggerId/pause
+ *   - POST   /v1/schedules/:triggerId/resume
+ *   - POST   /v1/schedules/:triggerId/unregister  (tombstone — GC per policy)
+ *
+ * The `triggerId` URL param is the trigger's id; the response body
+ * aliases it as `scheduleId` for a friendlier client surface.
+ */
+export function schedulesRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- POST / (register) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const flowId = requireString(body, 'flowId');
+    const flowVersion = requireString(body, 'flowVersion');
+    const cronExpression = requireString(body.config, 'config.cronExpression');
+    if (flowId.kind === 'err') return bad(c, requestId, flowId.message);
+    if (flowVersion.kind === 'err') return bad(c, requestId, flowVersion.message);
+    if (cronExpression.kind === 'err') return bad(c, requestId, cronExpression.message);
+
+    const rawConfig = (body.config ?? {}) as Record<string, unknown>;
+    const registerInput: RegisterCronTriggerInput = {
+      kind: 'cron',
+      tenantId,
+      flowId: flowId.value,
+      flowVersion: flowVersion.value,
+      config: {
+        cronExpression: cronExpression.value,
+        ...(typeof rawConfig.timezone === 'string' && { timezone: rawConfig.timezone }),
+        ...('input' in rawConfig && { input: rawConfig.input }),
+      },
+      ...(typeof body.label === 'string' && body.label.length > 0 && { label: body.label }),
+    };
+
+    const result = await binding.register(registerInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError({ code: result.error.code, message: result.error.message }, requestId),
+      );
+    }
+    c.status(201);
+    return c.json(serializeSchedule(result.value as CronTriggerRecord));
+  });
+
+  // ---------- GET / (list) ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+    const cursorRaw = c.req.query('cursor');
+    const statusRaw = c.req.query('status');
+
+    let statusFilter: 'active' | 'paused' | undefined;
+    if (statusRaw === 'active' || statusRaw === 'paused') statusFilter = statusRaw;
+
+    const page = await binding.list({
+      tenantId,
+      kind: 'cron',
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(statusFilter !== undefined && { status: statusFilter }),
+    });
+    return c.json({
+      data: page.data.map((row) => serializeSchedule(row as CronTriggerRecord)),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:triggerId (get) ----------
+  r.get('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const rec = await binding.get({ tenantId, triggerId });
+    if (rec === null || rec.kind !== 'cron') return notFound(c, requestId, triggerId);
+    return c.json(serializeSchedule(rec));
+  });
+
+  // ---------- PATCH /:triggerId (update) ----------
+  r.patch('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const patchConfig = body.config as Record<string, unknown> | undefined;
+    const cfg: Partial<{ cronExpression: string; timezone: string; input: unknown }> = {};
+    if (patchConfig !== undefined) {
+      if (typeof patchConfig.cronExpression === 'string')
+        cfg.cronExpression = patchConfig.cronExpression;
+      if (typeof patchConfig.timezone === 'string') cfg.timezone = patchConfig.timezone;
+      if ('input' in patchConfig) cfg.input = patchConfig.input;
+    }
+
+    const updateInput: UpdateCronTriggerInput = {
+      kind: 'cron',
+      tenantId,
+      triggerId,
+      ...(Object.keys(cfg).length > 0 && { config: cfg }),
+      ...('label' in body && { label: body.label === null ? null : (body.label as string) }),
+      ...(typeof body.flowVersion === 'string' && { flowVersion: body.flowVersion }),
+    };
+
+    const result = await binding.update(updateInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError(
+          {
+            code: result.error.code,
+            message: result.error.message,
+            triggerId: triggerId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeSchedule(result.value as CronTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/pause ----------
+  r.post('/:triggerId/pause', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.pause({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeSchedule(result.value as CronTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/resume ----------
+  r.post('/:triggerId/resume', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.resume({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeSchedule(result.value as CronTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/unregister (soft delete) ----------
+  r.post('/:triggerId/unregister', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const outcome = await binding.unregister({ tenantId, triggerId });
+    return c.json({
+      scheduleId: triggerId as unknown as string,
+      unregistered: outcome.unregistered,
+    });
+  });
+
+  return r;
+}
+
+// -----------------------------------------------------------------------
+// Shared helpers (co-located to keep each router self-contained).
+// -----------------------------------------------------------------------
+
+function serializeSchedule(r: CronTriggerRecord): Record<string, unknown> {
+  return {
+    scheduleId: r.triggerId as unknown as string,
+    triggerId: r.triggerId as unknown as string,
+    flowId: r.flowId,
+    flowVersion: r.flowVersion,
+    cronExpression: r.config.cronExpression,
+    ...(r.config.timezone !== undefined && { timezone: r.config.timezone }),
+    ...(r.config.input !== undefined && { input: r.config.input }),
+    label: r.label,
+    status: r.status,
+    nextFireAt: r.nextFireAt,
+    lastFiredAt: r.lastFiredAt,
+    createdAt: r.createdAt,
+    updatedAt: r.updatedAt,
+  };
+}
+
+type ParseOk<T> = { readonly kind: 'ok'; readonly value: T };
+type ParseErr = { readonly kind: 'err'; readonly response: Response };
+
+async function parseJsonObject(
+  c: Context<AppEnv>,
+  requestId: string,
+): Promise<ParseOk<Record<string, unknown>> | ParseErr> {
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      ),
+    };
+  }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError(
+          { code: 'bad-input', message: 'Request body must be a JSON object' },
+          requestId,
+        ),
+      ),
+    };
+  }
+  return { kind: 'ok', value: body as Record<string, unknown> };
+}
+
+function requireString(
+  obj: unknown,
+  path: string,
+):
+  | { readonly kind: 'ok'; readonly value: string }
+  | { readonly kind: 'err'; readonly message: string } {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== 'object') {
+      return { kind: 'err', message: `\`${path}\` is required` };
+    }
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  if (typeof cur !== 'string' || cur.length === 0) {
+    return { kind: 'err', message: `\`${path}\` is required` };
+  }
+  return { kind: 'ok', value: cur };
+}
+
+function bad(c: Context<AppEnv>, requestId: string, message: string): Response {
+  c.status(statusFor('bad-input') as never);
+  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+
+function notFound(c: Context<AppEnv>, requestId: string, triggerId: TriggerId): Response {
+  c.status(statusFor('trigger-not-found') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'trigger-not-found',
+        message: `No trigger with id "${triggerId as unknown as string}"`,
+        triggerId: triggerId as unknown as string,
+      },
+      requestId,
+    ),
+  );
+}
+
+function lifecycleError(
+  c: Context<AppEnv>,
+  requestId: string,
+  error: { readonly code: string; readonly message: string },
+  triggerId: TriggerId,
+): Response {
+  c.status(statusFor(error.code) as never);
+  return c.json(
+    toWireError(
+      { code: error.code, message: error.message, triggerId: triggerId as unknown as string },
+      requestId,
+    ),
+  );
+}

package/src/routes/scope-params.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type ResourceRef, ref } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { OrgId, ProjectId, TenantId } from '@kindgi/types';
+
+/**
+ * The authorization resource for a request scope: the project or org it
+ * names, else the tenant. A route's authorization middleware derives the
+ * scope with the same parser as its handler and passes the result here, so
+ * the scope that is checked is the scope that is acted on. An absent or
+ * unparseable scope checks the tenant, the strictest resource; the handler
+ * then rejects the request.
+ */
+export function scopeResourceRef(scope: Scope | undefined, tenantId: TenantId): ResourceRef {
+  if (scope?.kind === 'project') return ref('project', scope.projectId as unknown as string);
+  if (scope?.kind === 'org') return ref('org', scope.orgId as unknown as string);
+  return ref('tenant', tenantId as unknown as string);
+}
+
+/** {@link scopeResourceRef} for the `?scopeKind` + `?scopeId` query parameters. */
+export function queryScopeResourceRef(
+  query: QuerySource,
+  session: { readonly tenantId: TenantId },
+): ResourceRef {
+  const parsed = parseScopeParams(query, session);
+  return scopeResourceRef(parsed.kind === 'ok' ? parsed.scope : undefined, session.tenantId);
+}
+
+/**
+ * Outcome of parsing the `?scopeKind + ?scopeId + ?inherit` triplet.
+ * `ok` carries the decoded `Scope` (undefined if no scope params were
+ * supplied) plus the parsed `inherit` boolean (undefined if elided —
+ * caller leaves the binding to apply its own default).
+ */
+export type ParseScopeParamsOutcome =
+  | { readonly kind: 'ok'; readonly scope?: Scope; readonly inherit?: boolean }
+  | { readonly kind: 'err'; readonly message: string };
+
+type QuerySource = Record<string, string> | ((name: string) => string | undefined);
+
+/**
+ * Parse the `?scopeKind + ?scopeId + ?inherit` triplet. The wire shape
+ * is a discriminated triplet by design — human-readable, curl / browser
+ * / access-log auditable for regulated verticals.
+ *
+ * Cross-field validation (all return 400 `scope-invalid`):
+ * - `scopeKind === 'tenant' && scopeId !== undefined` → err (tenant carries no id).
+ * - `scopeKind in {'org','project'} && scopeId === undefined` → err (missing id).
+ * - `scopeKind === undefined && scopeId !== undefined` → err (orphan id).
+ * - `inherit` — accepts literal 'true' / 'false' strings; anything else → err.
+ *
+ * `tenantId` for the decoded Scope always comes from the session —
+ * cross-tenant scopes are denied by policy.
+ *
+ * `inherit` is load-bearing for policy/config-scoped bindings
+ * (e.g. MCP endpoints, secrets, env values) — controls the
+ * upward-hierarchy walk. For content-scoped bindings the flag is a
+ * documented no-op; the route passes it through so the binding-side
+ * field-passthrough shape stays uniform across the scope-aware
+ * bindings.
+ */
+export function parseScopeParams(
+  query: QuerySource,
+  session: { readonly tenantId: TenantId },
+): ParseScopeParamsOutcome {
+  const get: (n: string) => string | undefined =
+    typeof query === 'function' ? query : (n: string) => query[n];
+  const scopeKindRaw = get('scopeKind');
+  const scopeIdRaw = get('scopeId');
+  const inheritRaw = get('inherit');
+
+  // ---- inherit ----
+  let inherit: boolean | undefined;
+  if (inheritRaw !== undefined && inheritRaw.length > 0) {
+    if (inheritRaw === 'true') inherit = true;
+    else if (inheritRaw === 'false') inherit = false;
+    else {
+      return {
+        kind: 'err',
+        message: `scope query parameters malformed: inherit must be 'true' or 'false', got "${inheritRaw}"`,
+      };
+    }
+  }
+
+  // ---- scope triplet ----
+  if (scopeKindRaw === undefined || scopeKindRaw.length === 0) {
+    if (scopeIdRaw !== undefined && scopeIdRaw.length > 0) {
+      return {
+        kind: 'err',
+        message: `scope query parameters malformed: scopeId="${scopeIdRaw}" requires scopeKind`,
+      };
+    }
+    return { kind: 'ok', ...(inherit !== undefined && { inherit }) };
+  }
+
+  if (scopeKindRaw !== 'tenant' && scopeKindRaw !== 'org' && scopeKindRaw !== 'project') {
+    return {
+      kind: 'err',
+      message: `scope query parameters malformed: scopeKind must be one of 'tenant' | 'org' | 'project', got "${scopeKindRaw}"`,
+    };
+  }
+
+  if (scopeKindRaw === 'tenant') {
+    if (scopeIdRaw !== undefined && scopeIdRaw.length > 0) {
+      return {
+        kind: 'err',
+        message: `scope query parameters malformed: scopeKind='tenant' takes no scopeId (tenant is implicit from the session)`,
+      };
+    }
+    return {
+      kind: 'ok',
+      scope: { kind: 'tenant', tenantId: session.tenantId },
+      ...(inherit !== undefined && { inherit }),
+    };
+  }
+
+  // 'org' | 'project' — both require scopeId
+  if (scopeIdRaw === undefined || scopeIdRaw.length === 0) {
+    return {
+      kind: 'err',
+      message: `scope query parameters malformed: scopeKind='${scopeKindRaw}' requires scopeId`,
+    };
+  }
+
+  const scope: Scope =
+    scopeKindRaw === 'org'
+      ? { kind: 'org', tenantId: session.tenantId, orgId: scopeIdRaw as OrgId }
+      : { kind: 'project', tenantId: session.tenantId, projectId: scopeIdRaw as ProjectId };
+
+  return { kind: 'ok', scope, ...(inherit !== undefined && { inherit }) };
+}

package/src/routes/secret-ref.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type EnvName, makeEnvName } from '@kindgi/types';
+
+/** The longest secret name a `secretRef` can carry. */
+export const MAX_SECRET_NAME_LENGTH = 256;
+
+const SECRET_REF_FIELDS = new Set(['envName', 'name']);
+
+/**
+ * `{ envName, name }`: a secret by name in the deployment's secrets
+ * store, resolved at the owner's scope. The shape webhooks, MCP
+ * endpoints and providers share. `field` names it in messages.
+ */
+export function parseSecretRef(
+  raw: unknown,
+  field = 'secretRef',
+):
+  | { readonly kind: 'ok'; readonly value: { readonly envName: EnvName; readonly name: string } }
+  | { readonly kind: 'err'; readonly message: string; readonly unknownField?: string } {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { kind: 'err', message: `\`${field}\` must be an object \`{ envName, name }\`` };
+  }
+  const ref = raw as Record<string, unknown>;
+  const unknown = Object.keys(ref).find((key) => !SECRET_REF_FIELDS.has(key));
+  if (unknown !== undefined) {
+    return {
+      kind: 'err',
+      message: `Unknown field \`${field}.${unknown}\``,
+      unknownField: `${field}.${unknown}`,
+    };
+  }
+  const envName = typeof ref.envName === 'string' ? makeEnvName(ref.envName) : null;
+  if (envName === null) {
+    return {
+      kind: 'err',
+      message: `\`${field}.envName\` must be a lowercase name (letters, digits, hyphens)`,
+    };
+  }
+  if (
+    typeof ref.name !== 'string' ||
+    ref.name.length === 0 ||
+    ref.name.length > MAX_SECRET_NAME_LENGTH
+  ) {
+    return {
+      kind: 'err',
+      message: `\`${field}.name\` must be a non-empty string of at most ${MAX_SECRET_NAME_LENGTH} characters`,
+    };
+  }
+  return { kind: 'ok', value: { envName, name: ref.name } };
+}