@sixb/pg 0.0.1

package/src/pg-timeseries-storage.ts

@@ -0,0 +1,180 @@
+import type {
+  TimeseriesHistoryBatchInput,
+  TimeseriesHistoryBatchResult,
+  TimeseriesPoint,
+  TimeseriesStorage,
+} from "@sixb/core/storage"
+import type { SqlParameter } from "./pg-client"
+import type { PgStoreClient } from "./transactions"
+
+/**
+ * PostgreSQL-based TimeseriesStorage implementation.
+ *
+ * Stores time-series data with JSONB values and TIMESTAMPTZ timestamps
+ * for efficient querying of history and latest values.
+ *
+ * Requires `search_path` to be set to the Sixb schema on the connection.
+ */
+export class PgTimeseriesStorage implements TimeseriesStorage {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async getHistory(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+    from?: Date
+    to?: Date
+    limit?: number
+    order?: "asc" | "desc"
+  }): Promise<readonly TimeseriesPoint[]> {
+    const order = params.order ?? "asc"
+
+    // Build WHERE conditions using conditional fragments
+    const fromFilter = params.from ? this.sql`AND at >= ${params.from}` : this.sql``
+    const toFilter = params.to ? this.sql`AND at <= ${params.to}` : this.sql``
+    const limitFilter = params.limit !== undefined ? this.sql`LIMIT ${params.limit}` : this.sql``
+
+    const rows = await this.sql<TimeseriesDatabaseRow[]>`
+      SELECT * FROM timeseries
+      WHERE project_id = ${params.projectId}
+        AND object_type_id = ${params.objectTypeId}
+        AND object_id = ${params.objectId}
+        AND property_id = ${params.propertyId}
+        ${fromFilter}
+        ${toFilter}
+      ORDER BY at ${order === "asc" ? this.sql`ASC` : this.sql`DESC`}
+      ${limitFilter}
+    `
+
+    return rows.map((row) => rowToPoint(row))
+  }
+
+  async getHistoryBatch(
+    input: TimeseriesHistoryBatchInput
+  ): Promise<readonly TimeseriesHistoryBatchResult[]> {
+    if (input.series.length === 0) {
+      return []
+    }
+
+    const order = input.order === "desc" ? "DESC" : "ASC"
+    const params: unknown[] = []
+    let nextIndex = 1
+    const values = input.series
+      .map((series, seriesIndex) => {
+        const placeholders = [
+          `$${nextIndex++}`,
+          `$${nextIndex++}`,
+          `$${nextIndex++}`,
+          `$${nextIndex++}`,
+        ]
+        params.push(seriesIndex, series.objectTypeId, series.objectId, series.propertyId)
+        return `(${placeholders.join(", ")})`
+      })
+      .join(", ")
+
+    const projectIdPlaceholder = `$${nextIndex++}`
+    params.push(input.projectId)
+
+    const whereClauses = ["1 = 1"]
+    if (input.from) {
+      whereClauses.push(`timeseries.at >= $${nextIndex++}`)
+      params.push(input.from)
+    }
+    if (input.to) {
+      whereClauses.push(`timeseries.at <= $${nextIndex++}`)
+      params.push(input.to)
+    }
+
+    let query = `
+      WITH requested(series_index, object_type_id, object_id, property_id) AS (
+        VALUES ${values}
+      ),
+      ranked AS (
+        SELECT
+          requested.series_index,
+          timeseries.*,
+          ROW_NUMBER() OVER (
+            PARTITION BY requested.series_index
+            ORDER BY timeseries.at ${order}
+          ) AS series_row_number
+        FROM requested
+        JOIN timeseries
+          ON timeseries.project_id = ${projectIdPlaceholder}
+         AND timeseries.object_type_id = requested.object_type_id
+         AND timeseries.object_id = requested.object_id
+         AND timeseries.property_id = requested.property_id
+        WHERE ${whereClauses.join(" AND ")}
+      )
+      SELECT * FROM ranked
+    `
+
+    if (input.limitPerSeries !== undefined) {
+      query += ` WHERE series_row_number <= $${nextIndex++}`
+      params.push(Math.max(0, input.limitPerSeries))
+    }
+
+    query += ` ORDER BY series_index ASC, at ${order}`
+
+    const rows = await this.sql.unsafe<
+      (TimeseriesDatabaseRow & {
+        series_index: number | string
+        series_row_number: number | string
+      })[]
+    >(query, params as SqlParameter[])
+    const results = input.series.map((series) => ({
+      ...series,
+      points: [] as TimeseriesPoint[],
+    }))
+
+    for (const row of rows) {
+      const result = results[Number(row.series_index)]
+      if (result) {
+        result.points.push(rowToPoint(row))
+      }
+    }
+
+    return results
+  }
+
+  async getLatest(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+  }): Promise<TimeseriesPoint | null> {
+    const [row] = await this.sql<TimeseriesDatabaseRow[]>`
+      SELECT * FROM timeseries_latest
+      WHERE project_id = ${params.projectId}
+        AND object_type_id = ${params.objectTypeId}
+        AND object_id = ${params.objectId}
+        AND property_id = ${params.propertyId}
+    `
+
+    return row ? rowToPoint(row) : null
+  }
+}
+
+function rowToPoint(row: TimeseriesDatabaseRow): TimeseriesPoint {
+  return {
+    projectId: row.project_id,
+    objectTypeId: row.object_type_id,
+    objectId: row.object_id,
+    propertyId: row.property_id,
+    value: row.value,
+    unit: row.unit ?? undefined,
+    at: new Date(row.at),
+    lastCommitId: row.last_commit_id,
+  }
+}
+
+interface TimeseriesDatabaseRow {
+  project_id: string
+  object_type_id: string
+  object_id: string
+  property_id: string
+  value: unknown
+  unit: string | null
+  at: Date | string
+  last_commit_id: string
+}

package/src/pg-webhook-delivery-storage.ts

@@ -0,0 +1,180 @@
+import type {
+  WebhookDeliveryClaimRecord,
+  WebhookDeliveryClaimResult,
+  WebhookDeliveryKey,
+  WebhookDeliveryRecord,
+  WebhookDeliveryStorage,
+} from "@sixb/core/storage"
+import { type PgStoreClient, runPgTransaction } from "./transactions"
+
+export class PgWebhookDeliveryStorage implements WebhookDeliveryStorage {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async claim(
+    input: WebhookDeliveryKey & { receivedAt: string }
+  ): Promise<WebhookDeliveryClaimRecord> {
+    return runPgTransaction(this.sql, async (tx) => {
+      // Atomic first claim: only one transaction can insert this scoped delivery key.
+      const [inserted] = await tx<WebhookDeliveryRow[]>`
+        INSERT INTO webhook_deliveries (
+          project_id,
+          connector_id,
+          webhook_id,
+          idempotency_key,
+          status,
+          received_at
+        ) VALUES (
+          ${input.projectId},
+          ${input.connectorId},
+          ${input.webhookId},
+          ${input.idempotencyKey},
+          ${"in_progress"},
+          ${input.receivedAt}
+        )
+        ON CONFLICT (project_id, connector_id, webhook_id, idempotency_key) DO NOTHING
+        RETURNING *
+      `
+
+      if (inserted) {
+        return toWebhookDeliveryClaimRecord(inserted, "claimed")
+      }
+
+      const [existing] = await tx<WebhookDeliveryRow[]>`
+        SELECT * FROM webhook_deliveries
+        WHERE project_id = ${input.projectId}
+          AND connector_id = ${input.connectorId}
+          AND webhook_id = ${input.webhookId}
+          AND idempotency_key = ${input.idempotencyKey}
+        FOR UPDATE
+      `
+
+      if (existing?.status === "completed") {
+        return toWebhookDeliveryClaimRecord(existing, "duplicate")
+      }
+
+      if (existing?.status === "in_progress") {
+        return toWebhookDeliveryClaimRecord(existing, "in_progress")
+      }
+
+      if (existing?.status !== "failed") {
+        throw new Error("[SixbPg] Webhook delivery row disappeared during claim.")
+      }
+
+      // Failed deliveries are intentionally claimable so provider retries can run again.
+      const [updated] = await tx<WebhookDeliveryRow[]>`
+        UPDATE webhook_deliveries
+        SET status = ${"in_progress"},
+            received_at = ${input.receivedAt},
+            completed_at = ${null},
+            failed_at = ${null},
+            error = ${null}
+        WHERE project_id = ${input.projectId}
+          AND connector_id = ${input.connectorId}
+          AND webhook_id = ${input.webhookId}
+          AND idempotency_key = ${input.idempotencyKey}
+        RETURNING *
+      `
+
+      if (!updated) {
+        throw new Error(
+          `[SixbPg] Missing webhook delivery row after claim for ${serializeKey(input)}.`
+        )
+      }
+
+      return toWebhookDeliveryClaimRecord(updated, "claimed")
+    })
+  }
+
+  async complete(
+    input: WebhookDeliveryKey & { completedAt: string }
+  ): Promise<WebhookDeliveryRecord> {
+    const [updated] = await this.sql<WebhookDeliveryRow[]>`
+      UPDATE webhook_deliveries
+      SET status = ${"completed"},
+          completed_at = ${input.completedAt},
+          failed_at = ${null},
+          error = ${null}
+      WHERE project_id = ${input.projectId}
+        AND connector_id = ${input.connectorId}
+        AND webhook_id = ${input.webhookId}
+        AND idempotency_key = ${input.idempotencyKey}
+      RETURNING *
+    `
+
+    if (!updated) {
+      throw new Error(
+        `[SixbPg] Missing webhook delivery row after complete for ${serializeKey(input)}.`
+      )
+    }
+
+    return toWebhookDeliveryRecord(updated)
+  }
+
+  async fail(
+    input: WebhookDeliveryKey & { failedAt: string; error: string }
+  ): Promise<WebhookDeliveryRecord> {
+    const [updated] = await this.sql<WebhookDeliveryRow[]>`
+      UPDATE webhook_deliveries
+      SET status = ${"failed"},
+          failed_at = ${input.failedAt},
+          error = ${input.error}
+      WHERE project_id = ${input.projectId}
+        AND connector_id = ${input.connectorId}
+        AND webhook_id = ${input.webhookId}
+        AND idempotency_key = ${input.idempotencyKey}
+      RETURNING *
+    `
+
+    if (!updated) {
+      throw new Error(
+        `[SixbPg] Missing webhook delivery row after fail for ${serializeKey(input)}.`
+      )
+    }
+
+    return toWebhookDeliveryRecord(updated)
+  }
+}
+
+function toWebhookDeliveryClaimRecord(
+  row: WebhookDeliveryRow,
+  claimResult: WebhookDeliveryClaimResult
+): WebhookDeliveryClaimRecord {
+  return {
+    ...toWebhookDeliveryRecord(row),
+    claimResult,
+  }
+}
+
+function toWebhookDeliveryRecord(row: WebhookDeliveryRow): WebhookDeliveryRecord {
+  return {
+    projectId: row.project_id,
+    connectorId: row.connector_id,
+    webhookId: row.webhook_id,
+    idempotencyKey: row.idempotency_key,
+    status: row.status,
+    receivedAt: toIsoString(row.received_at),
+    completedAt: row.completed_at ? toIsoString(row.completed_at) : undefined,
+    failedAt: row.failed_at ? toIsoString(row.failed_at) : undefined,
+    error: row.error ?? undefined,
+  }
+}
+
+function toIsoString(value: Date | string): string {
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString()
+}
+
+function serializeKey(key: WebhookDeliveryKey): string {
+  return JSON.stringify([key.projectId, key.connectorId, key.webhookId, key.idempotencyKey])
+}
+
+interface WebhookDeliveryRow {
+  readonly project_id: string
+  readonly connector_id: string
+  readonly webhook_id: string
+  readonly idempotency_key: string
+  readonly status: WebhookDeliveryRecord["status"]
+  readonly received_at: Date | string
+  readonly completed_at: Date | string | null
+  readonly failed_at: Date | string | null
+  readonly error: string | null
+}

package/src/pg-webhook-run-storage.ts

@@ -0,0 +1,185 @@
+import type {
+  FinishWebhookRunInput,
+  ListWebhookRunsInput,
+  ListWebhookRunsResult,
+  StartWebhookRunInput,
+  WebhookRunRecord,
+  WebhookRunStorage,
+} from "@sixb/core/storage"
+import { WebhookRunError } from "@sixb/core/storage"
+import type { SqlParameter } from "./pg-client"
+import { appendRunListFilters, hasEmptyStatuses, queryRunList } from "./run-list-query"
+import { isUniqueViolation } from "./storage-errors"
+import { type PgStoreClient, runPgTransaction } from "./transactions"
+
+export class PgWebhookRunStorage implements WebhookRunStorage {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async start(input: StartWebhookRunInput): Promise<WebhookRunRecord> {
+    try {
+      const [row] = await this.sql<WebhookRunDatabaseRow[]>`
+        INSERT INTO webhook_runs (
+          project_id,
+          id,
+          connector_id,
+          webhook_id,
+          status,
+          method,
+          route,
+          started_at
+        ) VALUES (
+          ${input.projectId},
+          ${input.id},
+          ${input.connectorId},
+          ${input.webhookId},
+          ${"running"},
+          ${input.method},
+          ${input.route},
+          ${input.startedAt ?? new Date()}
+        )
+        RETURNING *
+      `
+
+      return rowToWebhookRunRecord(row)
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new WebhookRunError(
+          `[SixbPg] Webhook run '${input.id}' already exists for project '${input.projectId}'.`
+        )
+      }
+
+      throw error
+    }
+  }
+
+  async finish(input: FinishWebhookRunInput): Promise<WebhookRunRecord> {
+    return runPgTransaction(this.sql, async (tx) => {
+      const [existing] = await tx<WebhookRunDatabaseRow[]>`
+        SELECT * FROM webhook_runs
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        FOR UPDATE
+      `
+
+      if (!existing) {
+        throw new WebhookRunError(
+          `[SixbPg] Webhook run '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
+
+      if (existing.status !== "running") {
+        throw new WebhookRunError(
+          `[SixbPg] Webhook run '${input.id}' for project '${input.projectId}' is already terminal.`
+        )
+      }
+
+      const [updated] = await tx<WebhookRunDatabaseRow[]>`
+        UPDATE webhook_runs
+        SET
+          status = ${input.status},
+          finished_at = ${input.finishedAt ?? new Date()},
+          request_body_bytes = ${input.requestBodyBytes ?? null},
+          response_status = ${input.responseStatus ?? null},
+          idempotency_key = ${input.idempotencyKey ?? null},
+          delivery_claim_result = ${input.deliveryClaimResult ?? null},
+          error = ${input.status === "succeeded" ? null : (input.error ?? null)}
+        WHERE project_id = ${input.projectId} AND id = ${input.id}
+        RETURNING *
+      `
+
+      return rowToWebhookRunRecord(updated)
+    })
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<WebhookRunRecord | null> {
+    const [row] = await this.sql<WebhookRunDatabaseRow[]>`
+      SELECT * FROM webhook_runs
+      WHERE project_id = ${params.projectId} AND id = ${params.id}
+    `
+
+    return row ? rowToWebhookRunRecord(row) : null
+  }
+
+  async list(input: ListWebhookRunsInput): Promise<ListWebhookRunsResult> {
+    if (hasEmptyStatuses(input)) {
+      return {
+        runs: [],
+        hasMore: false,
+        total: 0,
+      }
+    }
+
+    const whereClauses = ["project_id = $1"]
+    const params: SqlParameter[] = [input.projectId]
+    let index = 2
+
+    if (input.connectorId) {
+      whereClauses.push(`connector_id = $${index++}`)
+      params.push(input.connectorId)
+    }
+
+    if (input.webhookId) {
+      whereClauses.push(`webhook_id = $${index++}`)
+      params.push(input.webhookId)
+    }
+
+    if (input.idempotencyKey) {
+      whereClauses.push(`idempotency_key = $${index++}`)
+      params.push(input.idempotencyKey)
+    }
+
+    index = appendRunListFilters(whereClauses, params, index, input)
+
+    const { rows, total, hasMore } = await queryRunList<WebhookRunDatabaseRow>({
+      sql: this.sql,
+      tableName: "webhook_runs",
+      whereClauses,
+      params,
+      nextIndex: index,
+      order: input.order,
+      limit: input.limit,
+      offset: input.offset,
+    })
+
+    return {
+      runs: rows.map(rowToWebhookRunRecord),
+      hasMore,
+      total,
+    }
+  }
+}
+
+function rowToWebhookRunRecord(row: WebhookRunDatabaseRow): WebhookRunRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    connectorId: row.connector_id,
+    webhookId: row.webhook_id,
+    status: row.status,
+    method: row.method,
+    route: row.route,
+    startedAt: new Date(row.started_at),
+    finishedAt: row.finished_at ? new Date(row.finished_at) : undefined,
+    requestBodyBytes: row.request_body_bytes != null ? Number(row.request_body_bytes) : undefined,
+    responseStatus: row.response_status != null ? Number(row.response_status) : undefined,
+    idempotencyKey: row.idempotency_key ?? undefined,
+    deliveryClaimResult: row.delivery_claim_result ?? undefined,
+    error: row.error ?? undefined,
+  }
+}
+
+interface WebhookRunDatabaseRow {
+  readonly project_id: string
+  readonly id: string
+  readonly connector_id: string
+  readonly webhook_id: string
+  readonly status: WebhookRunRecord["status"]
+  readonly method: string
+  readonly route: string
+  readonly started_at: Date | string
+  readonly finished_at: Date | string | null
+  readonly request_body_bytes: number | string | null
+  readonly response_status: number | string | null
+  readonly idempotency_key: string | null
+  readonly delivery_claim_result: WebhookRunRecord["deliveryClaimResult"] | null
+  readonly error: string | null
+}