@pawabase/client 0.0.0-stage → 0.1.0

package/src/manage/lifecycle.ts

@@ -0,0 +1,208 @@
+import { Service, seg, type Api, type Body } from "./base.js";
+
+type When = Date | string;
+const iso = (value?: When): string | undefined => (value instanceof Date ? value.toISOString() : value);
+
+/** The project's environments (`development`, `production`, previews…). Most calls here are not scoped to the client's environment. */
+export class Environments extends Service {
+  list(): Promise<Api> {
+    return this.project("GET", "/envs");
+  }
+
+  /** A new environment, optionally with another's definitions copied in. */
+  create(name: string, options: { copyFrom?: string } = {}): Promise<Api> {
+    return this.project("POST", "/envs", { body: { name, copy_from: options.copyFrom } });
+  }
+
+  getOne(name?: string): Promise<Api> {
+    return this.project("GET", `/envs/${encodeURIComponent(name ?? this.environment)}`);
+  }
+
+  /** Change an environment's infrastructure, sign-in settings or settings; each is merged in. */
+  update(name: string, changes: { infra?: Body; auth?: Body; settings?: Body; isDefault?: boolean }): Promise<Api> {
+    return this.project("PATCH", `/envs/${encodeURIComponent(name)}`, {
+      body: { infra: changes.infra, auth: changes.auth, settings: changes.settings, is_default: changes.isDefault },
+    });
+  }
+
+  deleteEnvironment(name: string): Promise<Api> {
+    return this.project("DELETE", `/envs/${encodeURIComponent(name)}`);
+  }
+
+  /** A short-lived copy for a branch or pull request (`ref`: lowercase letters, digits and hyphens); it expires by itself. */
+  createPreview(ref: string, options: { name?: string; expiresInHours?: number; infra?: Body; auth?: Body; settings?: Body } = {}): Promise<Api> {
+    return this.post("/previews", {
+      ref,
+      name: options.name,
+      expires_in_hours: options.expiresInHours ?? 72,
+      infra: options.infra ?? {},
+      auth: options.auth ?? {},
+      settings: options.settings,
+    });
+  }
+
+  deletePreview(preview: string): Promise<Api> {
+    return this.del(seg("previews", preview));
+  }
+
+  /** Copy this environment's definitions (never secrets or keys) to `to`. `include` limits the kinds (`flows`, `policies`, `resources`…). */
+  promote(to: string, options: { include?: string[] } = {}): Promise<Api> {
+    return this.post("/promote", { to, include: options.include });
+  }
+
+  /** Export definitions, roles and settings as a document another project can apply. */
+  blueprint(): Promise<Api> {
+    return this.get("/blueprint");
+  }
+
+  /** Build new environments from a blueprint; each must not exist yet. */
+  applyBlueprint(blueprint: Body, environments: string[] = ["development", "production"]): Promise<Api> {
+    return this.project("POST", "/blueprints/apply", { body: { blueprint, environments } });
+  }
+
+  /** Re-read the deployed function code now. */
+  reloadCode(): Promise<Api> {
+    return this.project("POST", "/code/reload");
+  }
+}
+
+/** Feature branches of the definitions, immutable revisions, API versions and releases. */
+export class Releases extends Service {
+  branches(): Promise<Api> {
+    return this.get("/branches");
+  }
+
+  createBranch(name: string, options: { fromBranch?: string; fromRevision?: string; protected?: boolean } = {}): Promise<Api> {
+    return this.post("/branches", { name, from_branch: options.fromBranch, from_revision: options.fromRevision, protected: options.protected ?? false });
+  }
+
+  /** The branch's definitions as they stand now. */
+  draft(branch: string): Promise<Api> {
+    return this.get(seg("branches", branch, "draft"));
+  }
+
+  merge(branch: string, options: { target?: string; force?: boolean } = {}): Promise<Api> {
+    return this.post(seg("branches", branch, "merge"), { target: options.target ?? "main", force: options.force ?? false });
+  }
+
+  revisions(): Promise<Api> {
+    return this.get("/revisions");
+  }
+
+  revision(revisionId: string): Promise<Api> {
+    return this.get(seg("revisions", revisionId));
+  }
+
+  /** Freeze the branch's draft as a revision. */
+  commit(branch: string, message = ""): Promise<Api> {
+    return this.post(seg("branches", branch, "revisions"), { message });
+  }
+
+  apiVersions(): Promise<Api> {
+    return this.get("/api-versions");
+  }
+
+  createApiVersion(name: string, options: { isDefault?: boolean } = {}): Promise<Api> {
+    return this.post("/api-versions", { name, is_default: options.isDefault ?? false });
+  }
+
+  /** `status`: draft, active, deprecated, sunset, disabled. */
+  updateApiVersion(name: string, changes: { status?: string; isDefault?: boolean; sunsetAt?: When }): Promise<Api> {
+    return this.patch(seg("api-versions", name), { status: changes.status, is_default: changes.isDefault, sunset_at: iso(changes.sunsetAt) });
+  }
+
+  rollbackApiVersion(name: string): Promise<Api> {
+    return this.post(seg("api-versions", name, "rollback"));
+  }
+
+  releases(): Promise<Api> {
+    return this.get("/releases");
+  }
+
+  /** Make a revision the live definitions of an API version. */
+  release(revisionId: string, apiVersion: string, name: string, options: { notes?: string; allowBreaking?: boolean } = {}): Promise<Api> {
+    return this.post("/releases", { revision_id: revisionId, api_version: apiVersion, name, notes: options.notes ?? "", allow_breaking: options.allowBreaking ?? false });
+  }
+
+  activate(releaseId: string): Promise<Api> {
+    return this.post(seg("releases", releaseId, "activate"));
+  }
+
+  deployments(): Promise<Api> {
+    return this.get("/deployments");
+  }
+}
+
+export interface RestoreOptions {
+  /** Parts to restore: `definitions`, `settings`, `users`, `data`. Default: every part the file holds. */
+  include?: string[];
+  /** `merge` adds and updates; `replace` first removes what the chosen parts hold and needs `confirm`. */
+  strategy?: "merge" | "replace";
+  dryRun?: boolean;
+  /** For `replace`: the environment's name, typed out. */
+  confirm?: string;
+}
+
+/** Whole-environment backups you download, stored snapshots, and restores. */
+export class Backups extends Service {
+  /** A backup document: `definitions`, `settings`, `users` and, with `data`, rows (up to `maxRows` per table). */
+  download(options: { include?: string[]; data?: boolean; maxRows?: number } = {}): Promise<Api> {
+    return this.get("/backup", { include: options.include?.join(","), data: options.data ? "true" : undefined, max_rows: options.maxRows });
+  }
+
+  /** Put a downloaded backup back. */
+  restore(backup: Body, options: RestoreOptions = {}): Promise<Api> {
+    return this.post("/restore", { backup, include: options.include, strategy: options.strategy ?? "merge", dry_run: options.dryRun ?? false, confirm: options.confirm });
+  }
+
+  /** Automatic snapshots: `frequency` hourly, daily (at `hour` UTC) or weekly (on `weekday`, 0 = Monday); older ones are pruned past `keepLast` and `keepDays`. */
+  setSchedule(options: { enabled?: boolean; frequency?: "hourly" | "daily" | "weekly"; hour?: number; weekday?: number; keepLast?: number; keepDays?: number; include?: string[] } = {}): Promise<Api> {
+    return this.put("/backup-schedule", {
+      enabled: options.enabled ?? true,
+      frequency: options.frequency ?? "daily",
+      hour: options.hour ?? 3,
+      weekday: options.weekday ?? 0,
+      keep_last: options.keepLast ?? 7,
+      keep_days: options.keepDays ?? 30,
+      include: options.include ?? [],
+    });
+  }
+
+  snapshots(): Promise<Api> {
+    return this.get("/snapshots");
+  }
+
+  /** Take a snapshot now and keep it. */
+  snapshot(name = "", options: { note?: string; include?: string[] } = {}): Promise<Api> {
+    return this.post("/snapshots", { name, note: options.note ?? "", include: options.include });
+  }
+
+  /** Rename it, annotate it, or pin it so pruning keeps it. */
+  updateSnapshot(snapshotId: string, changes: { name?: string; note?: string; pinned?: boolean }): Promise<Api> {
+    return this.patch(seg("snapshots", snapshotId), changes);
+  }
+
+  removeSnapshot(snapshotId: string): Promise<Api> {
+    return this.del(seg("snapshots", snapshotId));
+  }
+
+  downloadSnapshot(snapshotId: string): Promise<Api> {
+    return this.get(seg("snapshots", snapshotId, "download"));
+  }
+
+  /** Check the stored snapshot is intact. */
+  verifySnapshot(snapshotId: string): Promise<Api> {
+    return this.post(seg("snapshots", snapshotId, "verify"));
+  }
+
+  /** Restore a snapshot; a snapshot of the current state is taken first unless `safetySnapshot` is `false`. */
+  restoreSnapshot(snapshotId: string, options: RestoreOptions & { safetySnapshot?: boolean } = {}): Promise<Api> {
+    return this.post(seg("snapshots", snapshotId, "restore"), {
+      include: options.include,
+      strategy: options.strategy ?? "merge",
+      dry_run: options.dryRun ?? false,
+      confirm: options.confirm,
+      safety_snapshot: options.safetySnapshot ?? true,
+    });
+  }
+}

package/src/manage/mail.ts

@@ -0,0 +1,22 @@
+import { Definitions, Service, type Api } from "./base.js";
+
+/** Templates (subject, HTML, text) for the mail flows, functions and sign-in send. */
+export class MailTemplates extends Definitions {
+  protected override readonly kind = "mail-templates";
+}
+
+export class Mail extends Service {
+  /** The delivery settings in effect (the password is never returned) and whether mail is being delivered. */
+  config(): Promise<Api> {
+    return this.get("/mail/config");
+  }
+
+  /** Messages sent or suppressed. `status`: `sent`, `failed`, `suppressed`. */
+  log(options: { status?: string; limit?: number } = {}): Promise<Api> {
+    return this.get("/mail/log", options);
+  }
+
+  sendTest(to: string[]): Promise<Api> {
+    return this.post("/mail/test", { to });
+  }
+}

package/src/manage/observe.ts

@@ -0,0 +1,226 @@
+import { Service, seg, type Api } from "./base.js";
+
+type When = Date | string;
+const iso = (value?: When): string | undefined => (value instanceof Date ? value.toISOString() : value);
+
+export class Observability extends Service {
+  /** The environment at a glance: traffic, errors, latency, workers, storage. */
+  overview(options: { range?: string } = {}): Promise<Api> {
+    return this.get("/overview", options);
+  }
+
+  /** Traffic over a `range` (`1h`, `24h`, `7d`…) or between `from` and `to`. */
+  analytics(options: { range?: string; from?: When; to?: When } = {}): Promise<Api> {
+    return this.get("/analytics", { range: options.range, from: iso(options.from), to: iso(options.to) });
+  }
+
+  /** Recent requests. `status` is an exact code or a class (`5xx`); `search` matches the path. */
+  requests(options: { status?: string; method?: string; search?: string; requestId?: string; limit?: number } = {}): Promise<Api> {
+    const { requestId, ...rest } = options;
+    return this.get("/requests", { ...rest, request_id: requestId });
+  }
+
+  /** One request: its logs, database calls, spans, and the traceback if it failed. */
+  request(requestId: string): Promise<Api> {
+    return this.get(seg("requests", requestId));
+  }
+
+  /** Search application and access logs. `after` continues from the last entry you saw. */
+  logs(options: { q?: string; minutes?: number; limit?: number; after?: When } = {}): Promise<Api> {
+    return this.get("/logs", { q: options.q || undefined, minutes: options.minutes ?? 60, limit: options.limit ?? 200, after: iso(options.after) });
+  }
+
+  errors(options: { minutes?: number } = {}): Promise<Api> {
+    return this.get("/observability/errors", options);
+  }
+
+  /** Per-route traffic, latency and errors. */
+  routes(options: { minutes?: number; limit?: number; sort?: string } = {}): Promise<Api> {
+    return this.get("/observability/routes", options);
+  }
+
+  route(method: string, route: string, options: { minutes?: number } = {}): Promise<Api> {
+    return this.get("/observability/routes/detail", { method, route, ...options });
+  }
+
+  /** CPU, memory and connection figures over time. */
+  system(options: { minutes?: number } = {}): Promise<Api> {
+    return this.get("/observability/system", options);
+  }
+
+  /** Findings the platform spotted: slow routes, missing indexes, noisy errors. */
+  advisor(options: { minutes?: number } = {}): Promise<Api> {
+    return this.get("/advisor", options);
+  }
+
+  /** Counters per minute. */
+  metrics(options: { name?: string; minutes?: number } = {}): Promise<Api> {
+    return this.get("/metrics", options);
+  }
+
+  /** The metrics you can chart or alarm on. */
+  metricCatalog(): Promise<Api> {
+    return this.get("/metric-catalog");
+  }
+
+  /** One metric over time; `comparePrevious` adds the span before it. */
+  metricSeries(metric = "requests", options: { minutes?: number; period?: number; comparePrevious?: boolean } = {}): Promise<Api> {
+    return this.get("/metric-series", { metric, minutes: options.minutes ?? 60, period: options.period, compare: options.comparePrevious ? "previous" : undefined });
+  }
+
+  workers(): Promise<Api> {
+    return this.get("/workers");
+  }
+
+  /** What the environment is running with. */
+  configuration(): Promise<Api> {
+    return this.get("/configuration");
+  }
+
+  capacity(): Promise<Api> {
+    return this.get("/capacity");
+  }
+}
+
+export interface AlarmInput {
+  name: string;
+  /** A name from {@link Observability.metricCatalog}. */
+  metric: string;
+  threshold: number;
+  comparison?: "gt" | "gte" | "lt" | "lte";
+  windowMinutes?: number;
+  breachesNeeded?: number;
+  recipients?: string[];
+  description?: string;
+  enabled?: boolean;
+  renotifyMinutes?: number;
+}
+
+/** Alarms on a metric: when it crosses `threshold` for `breachesNeeded` checks in a row, `recipients` are mailed. */
+export class Alarms extends Service {
+  list(): Promise<Api> {
+    return this.get("/alarms");
+  }
+
+  create(alarm: AlarmInput): Promise<Api> {
+    return this.post("/alarms", {
+      name: alarm.name,
+      metric: alarm.metric,
+      threshold: alarm.threshold,
+      comparison: alarm.comparison ?? "gt",
+      window_minutes: alarm.windowMinutes ?? 5,
+      breaches_needed: alarm.breachesNeeded ?? 1,
+      recipients: alarm.recipients ?? [],
+      description: alarm.description ?? "",
+      enabled: alarm.enabled ?? true,
+      renotify_minutes: alarm.renotifyMinutes ?? 0,
+    });
+  }
+
+  /** Change some fields, using the server's names (`mute_minutes: 60` silences it for an hour, `0` un-mutes). */
+  update(alarmId: string, changes: Record<string, unknown>): Promise<Api> {
+    return this.patch(seg("alarms", alarmId), changes);
+  }
+
+  remove(alarmId: string): Promise<Api> {
+    return this.del(seg("alarms", alarmId));
+  }
+
+  /** Evaluate it now. */
+  check(alarmId: string): Promise<Api> {
+    return this.post(seg("alarms", alarmId, "check"));
+  }
+
+  /** Send the notification mail now. */
+  test(alarmId: string): Promise<Api> {
+    return this.post(seg("alarms", alarmId, "test"));
+  }
+
+  /** When alarms fired and recovered: one alarm's, or all. */
+  history(alarmId?: string): Promise<Api> {
+    return alarmId ? this.get(seg("alarms", alarmId, "events")) : this.get("/alarm-events");
+  }
+}
+
+export interface StatusComponent {
+  name: string;
+  /** `gateway`, `api`, `auth`, `realtime`, `workers` (measured) or `manual`. */
+  source?: string;
+  description?: string;
+}
+
+/** The public status page and its incidents. */
+export class StatusPage extends Service {
+  page(): Promise<Api> {
+    return this.get("/status-page");
+  }
+
+  configure(options: { enabled?: boolean; title?: string; description?: string; contactUrl?: string; components?: StatusComponent[] } = {}): Promise<Api> {
+    return this.put("/status-page", {
+      enabled: options.enabled ?? true,
+      title: options.title ?? "Status",
+      description: options.description ?? "",
+      contact_url: options.contactUrl ?? "",
+      components: options.components ?? [],
+    });
+  }
+
+  incidents(): Promise<Api> {
+    return this.get("/incidents");
+  }
+
+  /** `status`: investigating, identified, monitoring, resolved. `impact`: none, minor, major, critical. */
+  openIncident(title: string, options: { message?: string; status?: string; impact?: string; components?: string[] } = {}): Promise<Api> {
+    return this.post("/incidents", {
+      title,
+      message: options.message ?? "",
+      status: options.status ?? "investigating",
+      impact: options.impact ?? "minor",
+      components: options.components ?? [],
+    });
+  }
+
+  updateIncident(incidentId: string, message: string, options: { status: string; impact?: string }): Promise<Api> {
+    return this.post(seg("incidents", incidentId, "updates"), { status: options.status, message, impact: options.impact });
+  }
+
+  removeIncident(incidentId: string): Promise<Api> {
+    return this.del(seg("incidents", incidentId));
+  }
+}
+
+export interface AuditFilter {
+  action?: string;
+  actor?: string;
+  target?: string;
+  since?: When;
+  until?: When;
+  env?: string;
+}
+
+/** Service health, plan usage and the platform's own audit trail. */
+export class Health extends Service {
+  /** Each service (database, cache, queue, storage, mail…) with its state, latency and error rate. */
+  services(): Promise<Api> {
+    return this.get("/service-health");
+  }
+
+  /** Each plan limit and how much of it is used. */
+  usage(): Promise<Api> {
+    return this.get("/plan-usage");
+  }
+
+  retryPolicies(): Promise<Api> {
+    return this.project("GET", "/retry-policies");
+  }
+
+  /** Management-plane changes: who did what, to what, when. */
+  audit(filter: AuditFilter = {}): Promise<Api> {
+    return this.project("GET", "/audit", { query: { ...filter, since: iso(filter.since), until: iso(filter.until) } });
+  }
+
+  /** The audit trail as a file's contents (`jsonl` or `csv`), for the same filters as {@link audit}. */
+  exportAudit(filter: AuditFilter & { format?: "jsonl" | "csv" } = {}): Promise<string> {
+    return this.project<string>("GET", "/audit/export", { query: { ...filter, format: filter.format ?? "jsonl", since: iso(filter.since), until: iso(filter.until) }, parse: "text" });
+  }
+}

package/src/manage/realtime.ts

@@ -0,0 +1,95 @@
+import { type Api, Service, seg } from "./base.js";
+
+export type ChannelKind = "public" | "private" | "presence" | "protected" | "ephemeral" | "durable";
+
+export interface ChannelRule {
+  kind?: ChannelKind;
+  /** The policy that decides who may subscribe. Default `authenticated`. */
+  subscribe?: string;
+  /** The policy that decides who may publish. Default `authenticated`. */
+  publish?: string;
+  presence?: boolean;
+  /** How many recent messages are kept (0 to 1000). */
+  history?: number;
+  /** A limit of `0` means none. */
+  messageSizeLimit?: number;
+  publishRateLimit?: number;
+  subscriptionLimit?: number;
+  retentionSeconds?: number;
+  description?: string;
+}
+
+const wire = (rule: ChannelRule): Record<string, unknown> => {
+  const map: Record<string, unknown> = {
+    kind: rule.kind,
+    subscribe: rule.subscribe,
+    publish: rule.publish,
+    presence: rule.presence,
+    history: rule.history,
+    message_size_limit: rule.messageSizeLimit,
+    publish_rate_limit: rule.publishRateLimit,
+    subscription_limit: rule.subscriptionLimit,
+    retention_seconds: rule.retentionSeconds,
+    description: rule.description,
+  };
+  return Object.fromEntries(Object.entries(map).filter(([, value]) => value !== undefined));
+};
+
+/** Durable channel rules: a channel name pattern (`chat:*`), its kind, who may subscribe and publish, presence, history and limits. */
+export class RealtimeChannels extends Service {
+  list(): Promise<Api> {
+    return this.get("/realtime-channels");
+  }
+
+  /** Add a rule for channels matching `pattern`. */
+  create(pattern: string, rule: ChannelRule = {}): Promise<Api> {
+    return this.post("/realtime-channels", { pattern, ...wire(rule) });
+  }
+
+  update(channelId: string, changes: ChannelRule): Promise<Api> {
+    return this.patch(seg("realtime-channels", channelId), wire(changes));
+  }
+
+  remove(channelId: string): Promise<Api> {
+    return this.del(seg("realtime-channels", channelId));
+  }
+}
+
+/** Dashboards: read-only boards over your data, defined as JSON, optionally published at a public address. */
+export class Dashboards extends Service {
+  list(): Promise<Api> {
+    return this.get("/dashboards");
+  }
+
+  /** One dashboard with its full definition. */
+  getOne(dashboardId: string): Promise<Api> {
+    return this.get(seg("dashboards", dashboardId));
+  }
+
+  /** Make a dashboard (`name`: lowercase letters, digits and dashes). The definition is checked; a problem comes back as a 422 with the list. */
+  create(name: string, options: { definition?: Record<string, unknown>; title?: string; description?: string; enabled?: boolean } = {}): Promise<Api> {
+    return this.post("/dashboards", {
+      name,
+      title: options.title ?? "",
+      description: options.description ?? "",
+      definition: options.definition ?? { pages: [] },
+      enabled: options.enabled ?? true,
+    });
+  }
+
+  update(dashboardId: string, changes: { title?: string; description?: string; definition?: Record<string, unknown>; enabled?: boolean }): Promise<Api> {
+    return this.patch(seg("dashboards", dashboardId), Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined)));
+  }
+
+  remove(dashboardId: string): Promise<Api> {
+    return this.del(seg("dashboards", dashboardId));
+  }
+
+  /** Turn the public page on or off. Turning it on needs the environment's publishable key once (it is sealed and never returned). */
+  publish(dashboardId: string, options: { public: boolean; publishableKey?: string }): Promise<Api> {
+    return this.put(seg("dashboards", dashboardId, "publish"), {
+      public: options.public,
+      ...(options.publishableKey ? { publishable_key: options.publishableKey } : {}),
+    });
+  }
+}