spaps 0.7.5 → 0.7.7

package/src/domain-cli.js

@@ -0,0 +1,79 @@
+// Shared helper for thin CLI subcommands that proxy to SPAPS domain endpoints.
+// Reuses auth/client.js authFetch: SPAPS_ACCESS_TOKEN env or stored creds,
+// auto-refresh on 401. Domain commands focus on routing, not auth.
+
+const { authFetch, resolveServerUrl } = require('./auth/client');
+
+function normalizeError(err) {
+  if (err && err.code) return err;
+  const wrapped = new Error(err && err.message ? err.message : String(err));
+  wrapped.code = 'DOMAIN_REQUEST_FAILED';
+  return wrapped;
+}
+
+async function callEndpoint({ options = {}, method = 'GET', path, body = null, query = null } = {}) {
+  if (!path) throw new Error('callEndpoint requires a path');
+  const serverUrl = resolveServerUrl(options);
+  let fullPath = path;
+  if (query && typeof query === 'object') {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      params.append(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) fullPath = `${path}${path.includes('?') ? '&' : '?'}${qs}`;
+  }
+  try {
+    const res = await authFetch(fullPath, { serverUrl, method, body });
+    return {
+      status: res.status,
+      data: res.data,
+      ok: res.status >= 200 && res.status < 300,
+    };
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+function emit({ intent, result, isJson, successMessage = null }) {
+  if (isJson) {
+    console.log(JSON.stringify({
+      success: Boolean(result.ok),
+      command: intent,
+      status: result.status,
+      data: result.data,
+    }, null, 2));
+    return;
+  }
+  if (!result.ok) {
+    const msg = (result.data && (result.data.error?.message || result.data.message)) || `HTTP ${result.status}`;
+    console.error(`\u2717 ${intent}: ${msg}`);
+    return;
+  }
+  if (successMessage) {
+    console.log(successMessage);
+  }
+  try {
+    console.log(JSON.stringify(result.data, null, 2));
+  } catch {
+    console.log(String(result.data));
+  }
+}
+
+function emitAuthError(command, err, isJson) {
+  if (isJson) {
+    console.log(JSON.stringify({
+      success: false,
+      command,
+      error: { code: err.code || 'ERROR', message: err.message || String(err) },
+    }, null, 2));
+  } else {
+    const hint = err.code === 'NOT_AUTHENTICATED' || err.code === 'SESSION_EXPIRED'
+      ? ' (run `spaps login` first)'
+      : '';
+    console.error(`\u2717 ${command}: ${err.message}${hint}`);
+  }
+}
+
+module.exports = { callEndpoint, emit, emitAuthError };

package/src/domains.js

@@ -0,0 +1,193 @@
+/**
+ * Domain registry for SPAPS CLI.
+ *
+ * Each entry declares the routes a domain exposes and how the CLI should
+ * surface them: tool-spec entries, doctor mount probe, and metadata flags.
+ *
+ * Shape:
+ *   {
+ *     key: 'dayrate',
+ *     label: 'Dayrate',
+ *     probe: { method: 'GET', path: '/api/dayrate/availability' },
+ *     tools: [
+ *       { name, description, method, path,
+ *         parameters?: JSONSchema,
+ *         admin_required?: boolean,    // D1 + D5
+ *         agent_callable?: boolean }   // D5, default true
+ *     ]
+ *   }
+ *
+ * Path prefixes reflect the live backend routers as of 2026-04-16.
+ * Public = API key only. Admin = API key + JWT + admin role (admin_required:true).
+ * The CLI does not invent schemas; when OpenAPI is available ai-tool-spec.js
+ * enriches parameters/responses automatically.
+ */
+
+const DAYRATE = {
+  key: 'dayrate',
+  label: 'Dayrate',
+  probe: { method: 'GET', path: '/api/dayrate/availability' },
+  tools: [
+    { name: 'dayrate_availability', method: 'GET', path: '/api/dayrate/availability',
+      description: 'List bookable slots within the configured horizon with dynamic pricing.' },
+    { name: 'dayrate_book', method: 'POST', path: '/api/dayrate/book',
+      description: 'Book a single slot. Returns FreeBookResponse when an entitled user has remaining allotment, otherwise a Stripe Checkout URL.' },
+    { name: 'dayrate_book_multi', method: 'POST', path: '/api/dayrate/book-multi',
+      description: 'Book multiple slots in one Stripe session with running fill-rate pricing.' },
+    { name: 'dayrate_checkout_status', method: 'GET', path: '/api/dayrate/checkout-status',
+      description: 'Poll a Stripe session to learn the resulting booking status.' },
+    { name: 'dayrate_cancel', method: 'POST', path: '/api/dayrate/cancel',
+      description: 'Cancel an existing booking. Owner verified by user_id then email.' },
+    { name: 'dayrate_allotment', method: 'GET', path: '/api/dayrate/allotment',
+      description: 'Inspect free allotment status for a policy in the rolling window.' },
+    { name: 'dayrate_admin_get_config', method: 'GET', path: '/api/dayrate/admin/config',
+      description: 'Fetch dayrate pricing/availability config.', admin_required: true },
+    { name: 'dayrate_admin_update_config', method: 'PUT', path: '/api/dayrate/admin/config',
+      description: 'Upsert dayrate config (rates, tiers, horizon, timezone, slot definitions).', admin_required: true },
+    { name: 'dayrate_admin_list_bookings', method: 'GET', path: '/api/dayrate/admin/bookings',
+      description: 'Admin view of bookings with status/date/email/enrollment/user/is_free filters.', admin_required: true },
+    { name: 'dayrate_admin_list_policies', method: 'GET', path: '/api/dayrate/admin/policies',
+      description: 'List active booking policies.', admin_required: true },
+    { name: 'dayrate_admin_create_policy', method: 'POST', path: '/api/dayrate/admin/policies',
+      description: 'Create a booking policy (entitlement key, free allotment, overage rate, reschedule rules).', admin_required: true },
+    { name: 'dayrate_admin_update_policy', method: 'PUT', path: '/api/dayrate/admin/policies/{policy_id}',
+      description: 'Partial update of a booking policy.', admin_required: true },
+    { name: 'dayrate_admin_delete_policy', method: 'DELETE', path: '/api/dayrate/admin/policies/{policy_id}',
+      description: 'Delete a booking policy.', admin_required: true },
+  ],
+};
+
+const EMAIL = {
+  key: 'email',
+  label: 'Email',
+  probe: { method: 'GET', path: '/api/email/templates/__doctor__/preview', ok_on_404: true },
+  tools: [
+    { name: 'email_send', method: 'POST', path: '/api/email/send',
+      description: 'Send a transactional email by template key. In local mode Mailgun calls are short-circuited.' },
+    { name: 'email_get_template', method: 'GET', path: '/api/email/templates/{template_key}',
+      description: 'Fetch a template definition by key.' },
+    { name: 'email_preview_template', method: 'GET', path: '/api/email/templates/{template_key}/preview',
+      description: 'Render a template with its sample context.' },
+    { name: 'email_preview_template_with_context', method: 'POST', path: '/api/email/templates/{template_key}/preview',
+      description: 'Render a template with caller-provided context.' },
+    { name: 'email_list_logs', method: 'GET', path: '/api/email/logs',
+      description: 'List email sends. Non-admin users are scoped to their own logs; admins can filter by user_id or owner_id.' },
+    { name: 'email_admin_list_templates', method: 'GET', path: '/api/email/templates',
+      description: 'List all templates for the application.', admin_required: true },
+    { name: 'email_admin_create_template', method: 'POST', path: '/api/email/templates',
+      description: 'Create a template (subject, html, text, variables, sample context).', admin_required: true },
+    { name: 'email_admin_update_template', method: 'PUT', path: '/api/email/templates/{template_key}',
+      description: 'Update an existing template.', admin_required: true },
+    { name: 'email_admin_get_override', method: 'GET', path: '/api/email/templates/{template_key}/override',
+      description: 'Get subject/body override for a template.' },
+    { name: 'email_admin_set_override', method: 'PUT', path: '/api/email/templates/{template_key}/override',
+      description: 'Set subject/body override for a template.', admin_required: true },
+    { name: 'email_admin_clear_override', method: 'DELETE', path: '/api/email/templates/{template_key}/override',
+      description: 'Clear subject/body override for a template.', admin_required: true },
+  ],
+};
+
+const WEBHOOKS = {
+  key: 'webhooks',
+  label: 'Webhooks',
+  probe: { method: 'GET', path: '/api/webhooks/events' },
+  tools: [
+    { name: 'webhook_list', method: 'GET', path: '/api/webhooks',
+      description: 'List registered outbound webhooks.' },
+    { name: 'webhook_register', method: 'POST', path: '/api/webhooks',
+      description: 'Register an outbound webhook. The create response returns a one-time signing_secret.' },
+    { name: 'webhook_update', method: 'PUT', path: '/api/webhooks/{webhook_id}',
+      description: 'Update url, events, is_active, or headers on an existing webhook.' },
+    { name: 'webhook_delete', method: 'DELETE', path: '/api/webhooks/{webhook_id}',
+      description: 'Remove a registered webhook.' },
+    { name: 'webhook_deliveries', method: 'GET', path: '/api/webhooks/{webhook_id}/deliveries',
+      description: 'List delivery attempts for a webhook.' },
+    { name: 'webhook_events', method: 'GET', path: '/api/webhooks/events',
+      description: 'List supported outbound event types.' },
+    { name: 'webhook_mailgun_inbound', method: 'POST', path: '/api/webhooks/mailgun/events',
+      description: 'Mailgun inbound event receiver. Signature-verified; not callable from agents.',
+      agent_callable: false },
+  ],
+};
+
+const POLICIES = {
+  key: 'policies',
+  label: 'Policies',
+  // /policies/evaluations is admin-gated; 401/403 still proves the router is mounted.
+  probe: { method: 'GET', path: '/api/policies/evaluations', ok_on_auth_error: true },
+  tools: [
+    { name: 'policy_authorize', method: 'POST', path: '/api/policies/authorize',
+      description: 'Evaluate a named policy against a user/context. Returns allow/deny with reasons.' },
+    { name: 'policy_admin_list', method: 'GET', path: '/api/policies',
+      description: 'List policies (is_active filter).', admin_required: true },
+    { name: 'policy_admin_create', method: 'POST', path: '/api/policies',
+      description: 'Create a policy (name, effect, conditions, priority, metadata).', admin_required: true },
+    { name: 'policy_admin_get', method: 'GET', path: '/api/policies/{policy_id}',
+      description: 'Fetch a single policy.', admin_required: true },
+    { name: 'policy_admin_update', method: 'PUT', path: '/api/policies/{policy_id}',
+      description: 'Partial update of a policy.', admin_required: true },
+    { name: 'policy_admin_delete', method: 'DELETE', path: '/api/policies/{policy_id}',
+      description: 'Delete a policy.', admin_required: true },
+    { name: 'policy_admin_evaluations', method: 'GET', path: '/api/policies/evaluations',
+      description: 'List policy evaluation audit logs.', admin_required: true },
+  ],
+};
+
+const ISSUE_REPORTING = {
+  key: 'issue_reporting',
+  label: 'Issue Reporting',
+  // /v1/issue-reports/status requires auth; any 401/403 still proves mounted.
+  probe: { method: 'GET', path: '/api/v1/issue-reports/status', ok_on_auth_error: true },
+  tools: [
+    { name: 'issue_report_create', method: 'POST', path: '/api/v1/issue-reports',
+      description: 'Create an issue report. Requires the issue_reporting capability.' },
+    { name: 'issue_report_list_mine', method: 'GET', path: '/api/v1/issue-reports',
+      description: 'List the caller\u2019s issue reports.' },
+    { name: 'issue_report_status', method: 'GET', path: '/api/v1/issue-reports/status',
+      description: 'Aggregate status for the caller\u2019s issues.' },
+    { name: 'issue_report_get', method: 'GET', path: '/api/v1/issue-reports/{report_id}',
+      description: 'Fetch a single issue report.' },
+    { name: 'issue_report_update_note', method: 'PATCH', path: '/api/v1/issue-reports/{report_id}',
+      description: 'Update the note on an existing report.' },
+    { name: 'issue_report_reply', method: 'POST', path: '/api/v1/issue-reports/{report_id}/replies',
+      description: 'Reply to an issue; creates a child report and reopens the linked support case.' },
+  ],
+};
+
+const DOMAINS = [DAYRATE, EMAIL, WEBHOOKS, POLICIES, ISSUE_REPORTING];
+
+function listDomains() {
+  return DOMAINS;
+}
+
+function findDomain(key) {
+  return DOMAINS.find((d) => d.key === key) || null;
+}
+
+function buildDomainTools({ includeNonAgent = false } = {}) {
+  const out = [];
+  for (const domain of DOMAINS) {
+    for (const t of domain.tools) {
+      const agentCallable = t.agent_callable !== false;
+      if (!agentCallable && !includeNonAgent) continue;
+      out.push({
+        name: t.name,
+        description: t.description,
+        method: t.method,
+        path: t.path,
+        parameters: t.parameters || { type: 'object', properties: {} },
+        domain: domain.key,
+        admin_required: Boolean(t.admin_required),
+        agent_callable: agentCallable,
+      });
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  DOMAINS,
+  listDomains,
+  findDomain,
+  buildDomainTools,
+};