@pikku/kysely 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -1,3 +1,75 @@
+## 0.13.1
+
+### Patch Changes
+
+- 13474a6: feat(scopes): grant scopes directly to a user, not only through roles
+
+  A scope can now be granted to a user directly, outside of any role.
+  `resolveScopes` returns the union of a user's role-derived scopes and their
+  direct grants, so a one-off capability no longer requires inventing a role.
+  - `@pikku/core`: `ScopeService` gains `addScopeToUser` / `removeScopeFromUser` /
+    `listUserScopes`.
+  - `@pikku/kysely`: a new `pikku_user_scope` table (FK into `pikku_scopes`, so the
+    database still refuses an undeclared grant; `ON DELETE CASCADE` from `user`,
+    so deleting a user takes their direct grants with it). `resolveScopes` unions
+    it with the role join.
+  - `@pikku/addon-console`: `scopeAddScopeToUser` / `scopeRemoveScopeFromUser`
+    (gated by `pikku:scopes:manage`), and `scopeListUserRoles` now also returns
+    `directScopes`.
+  - `@pikku/console`: a **Direct scopes** section in the user roles drawer to grant
+    and revoke scopes directly, showing them distinctly from the resolved union.
+
+  Also: the Scopes page now distinguishes a permission error (a console admin
+  without `pikku:scopes:read`) from an actual scope-service outage, instead of
+  showing "the scope service may be unavailable" for both.
+
+- 13474a6: feat: KyselyScopeService — resolve and administer user scopes
+
+  Adds `KyselyScopeService`, backing the core `ScopeService` interface with four
+  self-created tables: `pikku_scopes`, `pikku_roles`, `pikku_role_scopes` and
+  `pikku_user_role`.
+
+  Scopes are declared in code and synced additively — a scope that is no longer
+  declared is marked, never deleted, so a rename or a rolling deploy cannot
+  silently revoke a grant. `pikku scopes prune` is the deliberate removal path.
+  Roles are data, composed by admins at runtime, and `pikku_role_scopes` has a
+  foreign key into `pikku_scopes`, so the database itself refuses to grant a
+  scope that was never declared.
+
+- 13474a6: feat: ScopeService.listScopes
+
+  Exposes the scope vocabulary held in the store — everything a role can be
+  composed from — flagging any scope that is still present but no longer declared
+  in code (inert, and awaiting `pikku scopes prune`).
+
+- 70fa400: Add outgoing webhooks — `webhookService.send()` enqueues signed deliveries onto a retrying queue, `@pikku/kysely`'s `KyselyWebhookService` persists per-attempt delivery history, and `@pikku/console` gains a read-only `/webhooks` page; also caches resolved secrets in `TypedSecretService` and registers inline-`func` metadata for queue/scheduler/trigger/gateway wirings.
+- Updated dependencies [7ab5287]
+- Updated dependencies [e86bc17]
+- Updated dependencies [a9b96a0]
+- Updated dependencies [3f7fc54]
+- Updated dependencies [c478794]
+- Updated dependencies [3f04ae4]
+- Updated dependencies [90d9f04]
+- Updated dependencies [cb079cc]
+- Updated dependencies [cb079cc]
+- Updated dependencies [0a7db82]
+- Updated dependencies [981c4db]
+- Updated dependencies [13474a6]
+- Updated dependencies [5a2b0d5]
+- Updated dependencies [13474a6]
+- Updated dependencies [ee040dc]
+- Updated dependencies [cb079cc]
+- Updated dependencies [13474a6]
+- Updated dependencies [9f0d0eb]
+- Updated dependencies [13474a6]
+- Updated dependencies [70fa400]
+- Updated dependencies [7b2ea23]
+- Updated dependencies [1dc77d5]
+- Updated dependencies [416606c]
+- Updated dependencies [d2a6eea]
+- Updated dependencies [30e62ee]
+  - @pikku/core@0.12.64
+
 ## 0.13.0
 
 ### Minor Changes

package/dist/src/index.d.ts

@@ -12,6 +12,8 @@ export type { KyselySecretServiceConfig } from './kysely-secret-service.js';
 export { KyselyCredentialService } from './kysely-credential-service.js';
 export type { KyselyCredentialServiceConfig } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
+export { KyselyScopeService } from './kysely-scope-service.js';
+export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, type CreateAuditedKyselyOptions, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
 export { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, type Serializer, type Deserializer, type SerializePluginOptions, } from './serialize-plugin.js';

package/dist/src/index.js

@@ -10,6 +10,8 @@ export { KyselyAIRunStateService } from './kysely-ai-run-state-service.js';
 export { KyselySecretService } from './kysely-secret-service.js';
 export { KyselyCredentialService } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
+export { KyselyScopeService } from './kysely-scope-service.js';
+export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
 export { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, } from './serialize-plugin.js';

package/dist/src/kysely-scope-service.d.ts

@@ -0,0 +1,59 @@
+import type { Role, ScopeService } from '@pikku/core/services';
+import type { FlatScope } from '@pikku/core/scope';
+import type { Kysely } from 'kysely';
+import type { KyselyPikkuDB } from './kysely-tables.js';
+/**
+ * Resolves and administers user scopes against four self-created tables.
+ *
+ * Requires better-auth: `pikku_user_role.user_id` references its `user` table
+ * with ON DELETE CASCADE, so deleting a user takes their grants with it. That
+ * table is created by better-auth's own migrations, which `pikku db migrate`
+ * hard-fails without, so it exists before `init()` runs.
+ *
+ * Scopes are declared in code and synced here; roles are data, composed by
+ * admins at runtime. `pikku_role_scopes` FKs into `pikku_scopes`, so the
+ * database itself refuses to grant a scope that was never declared.
+ */
+export declare class KyselyScopeService implements ScopeService {
+    private db;
+    private initialized;
+    constructor(db: Kysely<KyselyPikkuDB>);
+    init(): Promise<void>;
+    /**
+     * Registers the declared scope set.
+     *
+     * Additive: rows are upserted and anything no longer declared is *marked*
+     * (`declared = false`), never deleted. Marking is non-destructive, so a
+     * rename, a rollback, or a rolling deploy where an older replica is still
+     * serving cannot silently strip a grant. `pruneScopes` is the deliberate
+     * removal path.
+     */
+    syncScopes(scopes: FlatScope[]): Promise<void>;
+    resolveScopes(userId: string): Promise<string[]>;
+    listScopes(): Promise<Array<FlatScope & {
+        declared: boolean;
+    }>>;
+    createRole(role: Role): Promise<void>;
+    deleteRole(name: string): Promise<void>;
+    setRoleScopes(name: string, scopes: string[]): Promise<void>;
+    listRoles(): Promise<Role[]>;
+    addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
+    removeUserFromRole(userId: string, role: string): Promise<void>;
+    listUserRoles(userId: string): Promise<string[]>;
+    addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
+    removeScopeFromUser(userId: string, scope: string): Promise<void>;
+    listUserScopes(userId: string): Promise<string[]>;
+    /**
+     * Scopes marked undeclared by the last sync, with the roles that would lose
+     * them. Powers `pikku scopes audit`.
+     */
+    findStaleScopes(): Promise<Array<{
+        scope: string;
+        roles: string[];
+    }>>;
+    /**
+     * Removes undeclared scopes, cascading them out of every role that holds
+     * them. This revokes access, so it is never run implicitly.
+     */
+    pruneScopes(): Promise<string[]>;
+}

package/dist/src/kysely-scope-service.js

@@ -0,0 +1,268 @@
+import { sql } from 'kysely';
+/**
+ * Resolves and administers user scopes against four self-created tables.
+ *
+ * Requires better-auth: `pikku_user_role.user_id` references its `user` table
+ * with ON DELETE CASCADE, so deleting a user takes their grants with it. That
+ * table is created by better-auth's own migrations, which `pikku db migrate`
+ * hard-fails without, so it exists before `init()` runs.
+ *
+ * Scopes are declared in code and synced here; roles are data, composed by
+ * admins at runtime. `pikku_role_scopes` FKs into `pikku_scopes`, so the
+ * database itself refuses to grant a scope that was never declared.
+ */
+export class KyselyScopeService {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() {
+        if (this.initialized) {
+            return;
+        }
+        await this.db.schema
+            .createTable('pikku_scopes')
+            .ifNotExists()
+            .addColumn('name', 'text', (col) => col.primaryKey())
+            .addColumn('description', 'text')
+            .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull())
+            .execute();
+        await this.db.schema
+            .createTable('pikku_roles')
+            .ifNotExists()
+            .addColumn('name', 'text', (col) => col.primaryKey())
+            .addColumn('description', 'text')
+            .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .execute();
+        await this.db.schema
+            .createTable('pikku_role_scopes')
+            .ifNotExists()
+            .addColumn('role', 'text', (col) => col.notNull().references('pikku_roles.name').onDelete('cascade'))
+            .addColumn('scope', 'text', (col) => col.notNull().references('pikku_scopes.name').onDelete('cascade'))
+            .addPrimaryKeyConstraint('pikku_role_scopes_pk', ['role', 'scope'])
+            .execute();
+        await this.db.schema
+            .createTable('pikku_user_role')
+            .ifNotExists()
+            .addColumn('user_id', 'text', (col) => col.notNull().references('user.id').onDelete('cascade'))
+            .addColumn('role', 'text', (col) => col.notNull().references('pikku_roles.name').onDelete('cascade'))
+            .addColumn('granted_by', 'text')
+            .addColumn('granted_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('pikku_user_role_pk', ['user_id', 'role'])
+            .execute();
+        await this.db.schema
+            .createTable('pikku_user_scope')
+            .ifNotExists()
+            .addColumn('user_id', 'text', (col) => col.notNull().references('user.id').onDelete('cascade'))
+            .addColumn('scope', 'text', (col) => col.notNull().references('pikku_scopes.name').onDelete('cascade'))
+            .addColumn('granted_by', 'text')
+            .addColumn('granted_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('pikku_user_scope_pk', ['user_id', 'scope'])
+            .execute();
+        await this.db.schema
+            .createIndex('pikku_role_scopes_scope_idx')
+            .ifNotExists()
+            .on('pikku_role_scopes')
+            .column('scope')
+            .execute();
+        await this.db.schema
+            .createIndex('pikku_user_role_role_idx')
+            .ifNotExists()
+            .on('pikku_user_role')
+            .column('role')
+            .execute();
+        this.initialized = true;
+    }
+    /**
+     * Registers the declared scope set.
+     *
+     * Additive: rows are upserted and anything no longer declared is *marked*
+     * (`declared = false`), never deleted. Marking is non-destructive, so a
+     * rename, a rollback, or a rolling deploy where an older replica is still
+     * serving cannot silently strip a grant. `pruneScopes` is the deliberate
+     * removal path.
+     */
+    async syncScopes(scopes) {
+        await this.db.transaction().execute(async (trx) => {
+            if (scopes.length > 0) {
+                await trx
+                    .insertInto('pikkuScopes')
+                    .values(scopes.map((scope) => ({
+                    name: scope.id,
+                    description: scope.description ?? null,
+                    declared: true,
+                })))
+                    .onConflict((oc) => oc.column('name').doUpdateSet((eb) => ({
+                    description: eb.ref('excluded.description'),
+                    declared: true,
+                })))
+                    .execute();
+            }
+            const markStale = trx.updateTable('pikkuScopes').set({ declared: false });
+            await (scopes.length > 0
+                ? markStale.where('name', 'not in', scopes.map((s) => s.id))
+                : markStale).execute();
+        });
+    }
+    async resolveScopes(userId) {
+        const roleScopes = this.db
+            .selectFrom('pikkuUserRole')
+            .innerJoin('pikkuRoleScopes', 'pikkuRoleScopes.role', 'pikkuUserRole.role')
+            .select('pikkuRoleScopes.scope')
+            .where('pikkuUserRole.userId', '=', userId);
+        const directScopes = this.db
+            .selectFrom('pikkuUserScope')
+            .select('pikkuUserScope.scope')
+            .where('pikkuUserScope.userId', '=', userId);
+        const rows = await roleScopes.union(directScopes).execute();
+        return rows.map((row) => row.scope);
+    }
+    async listScopes() {
+        const rows = await this.db
+            .selectFrom('pikkuScopes')
+            .select(['name', 'description', 'declared'])
+            .execute();
+        return rows.map((row) => ({
+            id: row.name,
+            description: row.description ?? undefined,
+            declared: !!row.declared,
+        }));
+    }
+    async createRole(role) {
+        await this.db.transaction().execute(async (trx) => {
+            await trx
+                .insertInto('pikkuRoles')
+                .values({ name: role.name, description: role.description ?? null })
+                .execute();
+            if (role.scopes.length > 0) {
+                await trx
+                    .insertInto('pikkuRoleScopes')
+                    .values(role.scopes.map((scope) => ({ role: role.name, scope })))
+                    .execute();
+            }
+        });
+    }
+    async deleteRole(name) {
+        await this.db.deleteFrom('pikkuRoles').where('name', '=', name).execute();
+    }
+    async setRoleScopes(name, scopes) {
+        await this.db.transaction().execute(async (trx) => {
+            await trx.deleteFrom('pikkuRoleScopes').where('role', '=', name).execute();
+            if (scopes.length > 0) {
+                await trx
+                    .insertInto('pikkuRoleScopes')
+                    .values(scopes.map((scope) => ({ role: name, scope })))
+                    .execute();
+            }
+        });
+    }
+    async listRoles() {
+        const roles = await this.db
+            .selectFrom('pikkuRoles')
+            .select(['name', 'description'])
+            .execute();
+        const scopeRows = await this.db
+            .selectFrom('pikkuRoleScopes')
+            .select(['role', 'scope'])
+            .execute();
+        const byRole = new Map();
+        for (const row of scopeRows) {
+            const existing = byRole.get(row.role);
+            if (existing) {
+                existing.push(row.scope);
+            }
+            else {
+                byRole.set(row.role, [row.scope]);
+            }
+        }
+        return roles.map((role) => ({
+            name: role.name,
+            description: role.description ?? undefined,
+            scopes: byRole.get(role.name) ?? [],
+        }));
+    }
+    async addUserToRole(userId, role, grantedBy) {
+        await this.db
+            .insertInto('pikkuUserRole')
+            .values({ userId, role, grantedBy: grantedBy ?? null })
+            .onConflict((oc) => oc.columns(['userId', 'role']).doNothing())
+            .execute();
+    }
+    async removeUserFromRole(userId, role) {
+        await this.db
+            .deleteFrom('pikkuUserRole')
+            .where('userId', '=', userId)
+            .where('role', '=', role)
+            .execute();
+    }
+    async listUserRoles(userId) {
+        const rows = await this.db
+            .selectFrom('pikkuUserRole')
+            .select('role')
+            .where('userId', '=', userId)
+            .execute();
+        return rows.map((row) => row.role);
+    }
+    async addScopeToUser(userId, scope, grantedBy) {
+        await this.db
+            .insertInto('pikkuUserScope')
+            .values({ userId, scope, grantedBy: grantedBy ?? null })
+            .onConflict((oc) => oc.columns(['userId', 'scope']).doNothing())
+            .execute();
+    }
+    async removeScopeFromUser(userId, scope) {
+        await this.db
+            .deleteFrom('pikkuUserScope')
+            .where('userId', '=', userId)
+            .where('scope', '=', scope)
+            .execute();
+    }
+    async listUserScopes(userId) {
+        const rows = await this.db
+            .selectFrom('pikkuUserScope')
+            .select('scope')
+            .where('userId', '=', userId)
+            .execute();
+        return rows.map((row) => row.scope);
+    }
+    /**
+     * Scopes marked undeclared by the last sync, with the roles that would lose
+     * them. Powers `pikku scopes audit`.
+     */
+    async findStaleScopes() {
+        const stale = await this.db
+            .selectFrom('pikkuScopes')
+            .leftJoin('pikkuRoleScopes', 'pikkuRoleScopes.scope', 'pikkuScopes.name')
+            .select(['pikkuScopes.name as scope', 'pikkuRoleScopes.role as role'])
+            .where('pikkuScopes.declared', '=', false)
+            .execute();
+        const byScope = new Map();
+        for (const row of stale) {
+            const roles = byScope.get(row.scope) ?? [];
+            if (row.role) {
+                roles.push(row.role);
+            }
+            byScope.set(row.scope, roles);
+        }
+        return [...byScope.entries()].map(([scope, roles]) => ({ scope, roles }));
+    }
+    /**
+     * Removes undeclared scopes, cascading them out of every role that holds
+     * them. This revokes access, so it is never run implicitly.
+     */
+    async pruneScopes() {
+        const stale = await this.findStaleScopes();
+        if (stale.length === 0) {
+            return [];
+        }
+        const names = stale.map((s) => s.scope);
+        const deleted = await this.db
+            .deleteFrom('pikkuScopes')
+            .where('name', 'in', names)
+            .where('declared', '=', false)
+            .returning('name')
+            .execute();
+        return deleted.map((r) => r.name);
+    }
+}

package/dist/src/kysely-tables.d.ts

@@ -164,7 +164,72 @@ export interface UserSessionsTable {
     createdAt: Generated<Date>;
     updatedAt: Generated<Date>;
 }
+/**
+ * The declared scope set, synced from generated SCOPES.
+ *
+ * Additive: a scope removed from code leaves an inert row rather than
+ * cascading a grant away mid-deploy. `pikku scopes prune` removes them
+ * deliberately.
+ */
+export interface PikkuScopesTable {
+    name: string;
+    description: string | null;
+    /**
+     * False once a scope is no longer declared in code. Marking is
+     * non-destructive — grants survive until `pikku scopes prune` removes them
+     * deliberately.
+     */
+    declared: Generated<boolean>;
+}
+/** A role: an admin-composed bag of scopes. */
+export interface PikkuRolesTable {
+    name: string;
+    description: string | null;
+    createdAt: Generated<Date>;
+}
+export interface PikkuRoleScopesTable {
+    role: string;
+    scope: string;
+}
+export interface PikkuUserRoleTable {
+    userId: string;
+    role: string;
+    grantedBy: string | null;
+    grantedAt: Generated<Date>;
+}
+/** A scope granted directly to a user, outside of any role. */
+export interface PikkuUserScopeTable {
+    userId: string;
+    scope: string;
+    grantedBy: string | null;
+    grantedAt: Generated<Date>;
+}
+export interface WebhookDeliveryTable {
+    deliveryId: string;
+    organizationId: string | null;
+    url: string;
+    event: string | null;
+    status: Generated<'pending' | 'delivered' | 'failed'>;
+    attempts: Generated<number>;
+    createdAt: Generated<Date>;
+    updatedAt: Generated<Date>;
+    deliveredAt: Date | null;
+}
+export interface WebhookDeliveryAttemptTable {
+    attemptId: string;
+    deliveryId: string;
+    attemptNumber: number;
+    statusCode: number | null;
+    responseBody: string | null;
+    error: string | null;
+    createdAt: Generated<Date>;
+}
 export interface KyselyPikkuDB {
+    pikkuScopes: PikkuScopesTable;
+    pikkuRoles: PikkuRolesTable;
+    pikkuRoleScopes: PikkuRoleScopesTable;
+    pikkuUserRole: PikkuUserRoleTable;
+    pikkuUserScope: PikkuUserScopeTable;
     channels: ChannelsTable;
     channelSubscriptions: ChannelSubscriptionsTable;
     workflowRuns: WorkflowRunsTable;
@@ -183,4 +248,6 @@ export interface KyselyPikkuDB {
     credentials: CredentialsTable;
     credentialsAudit: CredentialsAuditTable;
     pikkuUserSessions: UserSessionsTable;
+    webhookDelivery: WebhookDeliveryTable;
+    webhookDeliveryAttempt: WebhookDeliveryAttemptTable;
 }

package/dist/src/kysely-webhook-service.d.ts

@@ -0,0 +1,27 @@
+import { QueueWebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts } from '@pikku/core/services';
+import type { QueueService } from '@pikku/core/queue';
+import type { Kysely } from 'kysely';
+import type { KyselyPikkuDB } from './kysely-tables.js';
+/**
+ * Durable {@link QueueWebhookService}: still delivers through the
+ * `pikku-outgoing-webhooks` queue, but records a `webhook_delivery` row per
+ * `send()` and one `webhook_delivery_attempt` row per try. Register it as the
+ * `webhookService` singleton; the queue worker persists each attempt through
+ * {@link recordAttempt}, overriding the base's throwing default.
+ */
+export declare class KyselyWebhookService extends QueueWebhookService {
+    private db;
+    private initialized;
+    constructor(queueService: QueueService, db: Kysely<KyselyPikkuDB>);
+    init(): Promise<void>;
+    send(input: SendWebhookInput): Promise<SendWebhookResult>;
+    recordAttempt(deliveryId: string, { statusCode, responseBody, error, delivered }: WebhookAttemptResult): Promise<void>;
+    /** List deliveries, most recent first — for the console webhooks view. */
+    listDeliveries(opts?: {
+        organizationId?: string;
+        limit?: number;
+    }): Promise<WebhookDeliveryRecord[]>;
+    /** A single delivery with its full attempt history, or null if unknown. */
+    getDelivery(deliveryId: string): Promise<WebhookDeliveryWithAttempts | null>;
+    private createIndexSafe;
+}

package/dist/src/kysely-webhook-service.js

@@ -0,0 +1,150 @@
+import { PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, QueueWebhookService, } from '@pikku/core/services';
+import { sql } from 'kysely';
+/**
+ * Durable {@link QueueWebhookService}: still delivers through the
+ * `pikku-outgoing-webhooks` queue, but records a `webhook_delivery` row per
+ * `send()` and one `webhook_delivery_attempt` row per try. Register it as the
+ * `webhookService` singleton; the queue worker persists each attempt through
+ * {@link recordAttempt}, overriding the base's throwing default.
+ */
+export class KyselyWebhookService extends QueueWebhookService {
+    db;
+    initialized = false;
+    constructor(queueService, db) {
+        super(queueService);
+        this.db = db;
+    }
+    async init() {
+        if (this.initialized) {
+            return;
+        }
+        await this.db.schema
+            .createTable('webhook_delivery')
+            .ifNotExists()
+            .addColumn('delivery_id', 'text', (col) => col.primaryKey())
+            .addColumn('organization_id', 'text')
+            .addColumn('url', 'text', (col) => col.notNull())
+            .addColumn('event', 'text')
+            .addColumn('status', 'text', (col) => col.defaultTo('pending').notNull())
+            .addColumn('attempts', 'integer', (col) => col.defaultTo(0).notNull())
+            .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updated_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('delivered_at', 'timestamp')
+            .execute();
+        await this.db.schema
+            .createTable('webhook_delivery_attempt')
+            .ifNotExists()
+            .addColumn('attempt_id', 'text', (col) => col.primaryKey())
+            .addColumn('delivery_id', 'text', (col) => col.notNull().references('webhook_delivery.delivery_id').onDelete('cascade'))
+            .addColumn('attempt_number', 'integer', (col) => col.notNull())
+            .addColumn('status_code', 'integer')
+            .addColumn('response_body', 'text')
+            .addColumn('error', 'text')
+            .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .execute();
+        await this.createIndexSafe(this.db.schema
+            .createIndex('idx_webhook_delivery_org')
+            .ifNotExists()
+            .on('webhook_delivery')
+            .column('organization_id'));
+        await this.createIndexSafe(this.db.schema
+            .createIndex('idx_webhook_delivery_attempt_delivery')
+            .ifNotExists()
+            .on('webhook_delivery_attempt')
+            .column('delivery_id'));
+        this.initialized = true;
+    }
+    async send(input) {
+        const deliveryId = globalThis.crypto.randomUUID();
+        const { jobData, options } = await this.prepareDelivery(input);
+        await this.db
+            .insertInto('webhookDelivery')
+            .values({
+            deliveryId,
+            organizationId: input.organizationId ?? null,
+            url: input.url,
+            event: input.event ?? null,
+        })
+            .execute();
+        // deliveryId doubles as the queue jobId (idempotency) and rides in the
+        // payload so the worker can record attempts against this row.
+        const jobId = await this.queueService.add(PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, { ...jobData, deliveryId }, { ...options, jobId: deliveryId });
+        return { jobId };
+    }
+    async recordAttempt(deliveryId, { statusCode, responseBody, error, delivered }) {
+        const now = new Date();
+        await this.db.transaction().execute(async (trx) => {
+            const existing = await trx
+                .selectFrom('webhookDeliveryAttempt')
+                .select((eb) => eb.fn.countAll().as('count'))
+                .where('deliveryId', '=', deliveryId)
+                .executeTakeFirst();
+            const attemptNumber = Number(existing?.count ?? 0) + 1;
+            await trx
+                .insertInto('webhookDeliveryAttempt')
+                .values({
+                attemptId: globalThis.crypto.randomUUID(),
+                deliveryId,
+                attemptNumber,
+                statusCode: statusCode ?? null,
+                responseBody: responseBody ?? null,
+                error: error ?? null,
+            })
+                .execute();
+            await trx
+                .updateTable('webhookDelivery')
+                .set({
+                status: delivered ? 'delivered' : 'failed',
+                attempts: attemptNumber,
+                updatedAt: now,
+                ...(delivered ? { deliveredAt: now } : {}),
+            })
+                .where('deliveryId', '=', deliveryId)
+                .execute();
+        });
+    }
+    /** List deliveries, most recent first — for the console webhooks view. */
+    async listDeliveries(opts) {
+        let query = this.db
+            .selectFrom('webhookDelivery')
+            .selectAll()
+            .orderBy('createdAt', 'desc')
+            .limit(opts?.limit ?? 100);
+        if (opts?.organizationId) {
+            query = query.where('organizationId', '=', opts.organizationId);
+        }
+        return query.execute();
+    }
+    /** A single delivery with its full attempt history, or null if unknown. */
+    async getDelivery(deliveryId) {
+        const delivery = await this.db
+            .selectFrom('webhookDelivery')
+            .selectAll()
+            .where('deliveryId', '=', deliveryId)
+            .executeTakeFirst();
+        if (!delivery) {
+            return null;
+        }
+        const attempts = await this.db
+            .selectFrom('webhookDeliveryAttempt')
+            .selectAll()
+            .where('deliveryId', '=', deliveryId)
+            .orderBy('attemptNumber', 'asc')
+            .execute();
+        return { delivery, attempts };
+    }
+    async createIndexSafe(builder) {
+        try {
+            await builder.execute();
+        }
+        catch (e) {
+            if (e?.code === 'ER_DUP_KEYNAME' || e?.errno === 1061)
+                return;
+            if (e?.code === '42P07')
+                return;
+            if (e?.message?.includes('already exists'))
+                return;
+            throw e;
+        }
+    }
+}