@smithers-orchestrator/control-plane 0.24.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/control-plane",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Durable organization, project, billing, usage, secret-reference, and audit primitives for hosted Smithers control planes.",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,7 @@
     "src/"
   ],
   "dependencies": {
-    "@smithers-orchestrator/errors": "0.24.2"
+    "@smithers-orchestrator/errors": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/index.d.ts

@@ -66,12 +66,14 @@ type ControlPlaneUsageEvent = {
   metadata: Record<string, unknown>;
 };
 
+type ControlPlaneUsageLimitPeriod = 'daily' | 'weekly' | 'monthly';
+
 type ControlPlaneUsageLimit = {
   orgId: string;
   projectId: string | null;
   metric: string;
   unit: string;
-  period: string;
+  period: ControlPlaneUsageLimitPeriod;
   limitQuantity: number;
   updatedAtMs: number;
 };
@@ -141,12 +143,12 @@ declare class ControlPlaneStore {
   listIdentityProviders(input: { orgId: string; status?: string }): ControlPlaneIdentityProvider[];
   recordUsage(input: { orgId: string; projectId?: string | null; runId?: string | null; metric: string; quantity: number; unit?: string; observedAtMs?: number; metadata?: Record<string, unknown> }): ControlPlaneUsageEvent;
   summarizeUsage(input: { orgId: string; sinceMs?: number; untilMs?: number }): ControlPlaneUsageSummary[];
-  setUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; limitQuantity: number; updatedAtMs?: number }): ControlPlaneUsageLimit;
-  checkUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; sinceMs?: number; untilMs?: number }): ControlPlaneUsageLimitCheck | null;
+  setUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: ControlPlaneUsageLimitPeriod; limitQuantity: number; updatedAtMs?: number }): ControlPlaneUsageLimit;
+  checkUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: ControlPlaneUsageLimitPeriod; sinceMs?: number; untilMs?: number }): ControlPlaneUsageLimitCheck | null;
   putSecretRef(input: { orgId: string; projectId?: string | null; name: string; provider: string; ref: string; createdBy?: string | null; createdAtMs?: number; rotatedAtMs?: number | null }): ControlPlaneSecretRef;
   listSecretRefs(input: { orgId: string; projectId?: string | null }): ControlPlaneSecretRef[];
   recordAuditEvent(input: { orgId: string; projectId?: string | null; actorId?: string | null; action: string; targetType: string; targetId?: string | null; occurredAtMs?: number; metadata?: Record<string, unknown> }): ControlPlaneAuditEvent;
   exportOrgAudit(input: { orgId: string; sinceMs?: number; untilMs?: number; exportedAtMs?: number }): ControlPlaneExport;
 }
 
-export { type ControlPlaneAuditEvent, type ControlPlaneBillingAccount, type ControlPlaneExport, type ControlPlaneIdentityProvider, type ControlPlaneOrg, type ControlPlaneProject, type ControlPlaneSecretRef, type ControlPlaneSqlite, ControlPlaneStore, type ControlPlaneTeam, type ControlPlaneUsageEvent, type ControlPlaneUsageLimit, type ControlPlaneUsageLimitCheck, type ControlPlaneUsageSummary, ensureControlPlaneTables };
+export { type ControlPlaneAuditEvent, type ControlPlaneBillingAccount, type ControlPlaneExport, type ControlPlaneIdentityProvider, type ControlPlaneOrg, type ControlPlaneProject, type ControlPlaneSecretRef, type ControlPlaneSqlite, ControlPlaneStore, type ControlPlaneTeam, type ControlPlaneUsageEvent, type ControlPlaneUsageLimit, type ControlPlaneUsageLimitCheck, type ControlPlaneUsageLimitPeriod, type ControlPlaneUsageSummary, ensureControlPlaneTables };

package/src/index.js

@@ -19,6 +19,11 @@ import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 
 const SLUG_RE = /^(?:[a-z0-9]|[a-z0-9][a-z0-9-]{0,62}[a-z0-9])$/;
 const ID_RE = /^[A-Za-z0-9:_-]{1,128}$/;
+const USAGE_LIMIT_PERIODS = new Map([
+    ["daily", 24 * 60 * 60 * 1000],
+    ["weekly", 7 * 24 * 60 * 60 * 1000],
+    ["monthly", 30 * 24 * 60 * 60 * 1000],
+]);
 
 /**
  * @param {ControlPlaneSqlite} sqlite
@@ -285,7 +290,16 @@ function parseJsonObject(value) {
     if (typeof value !== "string" || value.trim().length === 0) {
         return {};
     }
-    const parsed = JSON.parse(value);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        console.warn("control-plane: ignoring malformed metadata_json.", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return {};
+    }
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
 }
 
@@ -311,6 +325,17 @@ function quantity(value) {
     return n;
 }
 
+/**
+ * @param {unknown} value
+ */
+function usageLimitPeriod(value) {
+    const period = nonEmptyString("period", value);
+    if (!USAGE_LIMIT_PERIODS.has(period)) {
+        throw new SmithersError("INVALID_INPUT", "period must be one of: daily, weekly, monthly.", { period });
+    }
+    return period;
+}
+
 /**
  * @param {string | null} projectId
  */
@@ -318,6 +343,33 @@ function projectKey(projectId) {
     return projectId ?? "__org__";
 }
 
+/**
+ * @param {unknown} error
+ * @param {string} constraint
+ */
+function isUniqueConstraintError(error, constraint) {
+    return error instanceof Error && error.message.includes(`UNIQUE constraint failed: ${constraint}`);
+}
+
+/**
+ * @param {unknown} error
+ * @param {{ entity: "org" | "team" | "project"; slug: string; orgId?: string }} input
+ */
+function throwDuplicateSlugError(error, input) {
+    const details = {
+        kind: `control-plane.${input.entity}`,
+        id: input.slug,
+        slug: input.slug,
+        ...(input.orgId ? { orgId: input.orgId } : {}),
+    };
+    throw new SmithersError(
+        "DUPLICATE_ID",
+        `Duplicate control-plane ${input.entity} slug: ${input.slug}`,
+        details,
+        { cause: error },
+    );
+}
+
 /**
  * @param {Record<string, unknown>} row
  * @returns {ControlPlaneOrg}
@@ -421,7 +473,7 @@ function usageLimitRow(row) {
         projectId: row.projectId === null ? null : String(row.projectId),
         metric: String(row.metric),
         unit: String(row.unit),
-        period: String(row.period),
+        period: usageLimitPeriod(row.period),
         limitQuantity: Number(row.limitQuantity),
         updatedAtMs: Number(row.updatedAtMs),
     };
@@ -497,11 +549,20 @@ export class ControlPlaneStore {
      */
     createOrg(input) {
         const orgId = optionalId("orgId", input.orgId);
+        const orgSlug = slug("slug", input.slug);
         const createdAtMs = timestamp(input.createdAtMs);
-        this.sqlite.query(`
+        try {
+            this.sqlite.query(`
 INSERT INTO _smithers_cp_orgs (org_id, slug, name, created_at_ms)
 VALUES (?, ?, ?, ?)
-`).run(orgId, slug("slug", input.slug), nonEmptyString("name", input.name), createdAtMs);
+`).run(orgId, orgSlug, nonEmptyString("name", input.name), createdAtMs);
+        }
+        catch (error) {
+            if (isUniqueConstraintError(error, "_smithers_cp_orgs.slug")) {
+                throwDuplicateSlugError(error, { entity: "org", slug: orgSlug });
+            }
+            throw error;
+        }
         this.recordAuditEvent({
             orgId,
             actorId: "system",
@@ -534,11 +595,20 @@ LIMIT 1
     createTeam(input) {
         const orgId = requiredId("orgId", input.orgId);
         const teamId = optionalId("teamId", input.teamId);
+        const teamSlug = slug("slug", input.slug);
         const createdAtMs = timestamp(input.createdAtMs);
-        this.sqlite.query(`
+        try {
+            this.sqlite.query(`
 INSERT INTO _smithers_cp_teams (org_id, team_id, slug, name, created_at_ms)
 VALUES (?, ?, ?, ?, ?)
-`).run(orgId, teamId, slug("slug", input.slug), nonEmptyString("name", input.name), createdAtMs);
+`).run(orgId, teamId, teamSlug, nonEmptyString("name", input.name), createdAtMs);
+        }
+        catch (error) {
+            if (isUniqueConstraintError(error, "_smithers_cp_teams.org_id, _smithers_cp_teams.slug")) {
+                throwDuplicateSlugError(error, { entity: "team", slug: teamSlug, orgId });
+            }
+            throw error;
+        }
         this.recordAuditEvent({
             orgId,
             action: "team.create",
@@ -587,12 +657,21 @@ ON CONFLICT(org_id, team_id, user_id) DO UPDATE SET role = excluded.role
     createProject(input) {
         const orgId = requiredId("orgId", input.orgId);
         const projectId = optionalId("projectId", input.projectId);
+        const projectSlug = slug("slug", input.slug);
         const metadata = jsonObject(input.metadata);
         const createdAtMs = timestamp(input.createdAtMs);
-        this.sqlite.query(`
+        try {
+            this.sqlite.query(`
 INSERT INTO _smithers_cp_projects (org_id, project_id, slug, name, metadata_json, created_at_ms)
 VALUES (?, ?, ?, ?, ?, ?)
-`).run(orgId, projectId, slug("slug", input.slug), nonEmptyString("name", input.name), JSON.stringify(metadata), createdAtMs);
+`).run(orgId, projectId, projectSlug, nonEmptyString("name", input.name), JSON.stringify(metadata), createdAtMs);
+        }
+        catch (error) {
+            if (isUniqueConstraintError(error, "_smithers_cp_projects.org_id, _smithers_cp_projects.slug")) {
+                throwDuplicateSlugError(error, { entity: "project", slug: projectSlug, orgId });
+            }
+            throw error;
+        }
         this.recordAuditEvent({
             orgId,
             projectId,
@@ -753,6 +832,9 @@ ORDER BY provider_id
     recordUsage(input) {
         const orgId = requiredId("orgId", input.orgId);
         const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        if (projectId) {
+            assertProjectExists(this.sqlite, orgId, projectId);
+        }
         const observedAtMs = timestamp(input.observedAtMs);
         const metadata = jsonObject(input.metadata);
         this.sqlite.query(`
@@ -816,7 +898,7 @@ ORDER BY metric, unit
         }
         const metric = nonEmptyString("metric", input.metric);
         const unit = nonEmptyString("unit", input.unit ?? "count");
-        const period = nonEmptyString("period", input.period ?? "monthly");
+        const period = usageLimitPeriod(input.period ?? "monthly");
         const limitValue = quantity(input.limitQuantity);
         const updatedAtMs = timestamp(input.updatedAtMs);
         this.sqlite.query(`
@@ -854,7 +936,7 @@ LIMIT 1
         const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
         const metric = nonEmptyString("metric", input.metric);
         const unit = nonEmptyString("unit", input.unit ?? "count");
-        const period = nonEmptyString("period", input.period ?? "monthly");
+        const period = usageLimitPeriod(input.period ?? "monthly");
         const limitRowRaw = this.sqlite.query(`
 SELECT org_id AS orgId, project_id AS projectId, metric, unit, period, limit_quantity AS limitQuantity, updated_at_ms AS updatedAtMs
 FROM _smithers_cp_usage_limits
@@ -864,8 +946,9 @@ LIMIT 1
         if (!limitRowRaw) {
             return null;
         }
-        const sinceMs = input.sinceMs === undefined ? 0 : timestamp(input.sinceMs);
-        const untilMs = input.untilMs === undefined ? Number.MAX_SAFE_INTEGER : timestamp(input.untilMs);
+        const untilMs = input.untilMs === undefined ? timestamp(undefined) : timestamp(input.untilMs);
+        const periodMs = USAGE_LIMIT_PERIODS.get(period) ?? 0;
+        const sinceMs = input.sinceMs === undefined ? Math.max(0, untilMs - periodMs) : timestamp(input.sinceMs);
         const usageSql = projectId
             ? `
 SELECT COALESCE(SUM(quantity), 0) AS usedQuantity
@@ -979,6 +1062,9 @@ ORDER BY name
     recordAuditEvent(input) {
         const orgId = requiredId("orgId", input.orgId);
         const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        if (projectId) {
+            assertProjectExists(this.sqlite, orgId, projectId);
+        }
         const occurredAtMs = timestamp(input.occurredAtMs);
         const metadata = jsonObject(input.metadata);
         this.sqlite.query(`