@sylphx/contract 0.2.0

package/dist/schemas/webhooks.js

@@ -0,0 +1,198 @@
+/**
+ * Webhooks — Console-plane outgoing webhook configuration, delivery log,
+ * stats, replays, and super-admin cross-project operations. Distinct from
+ * the runtime webhook signature verification surface exposed in
+ * `@sylphx/sdk/server` (customer-side HMAC verify helpers are in the SDK,
+ * not a Platform API).
+ *
+ * Mirrors the wire shapes served at `/webhooks/*` in
+ * `apps/api/src/server/platform/routes/webhooks/*`.
+ *
+ * Every query param that arrives as a string on the wire stays
+ * `Schema.String`. Coercion happens in the handler.
+ */
+import { Schema } from 'effect';
+// ── Shared types ───────────────────────────────────────────────────────────
+export const WebhookStatus = Schema.Literal('pending', 'queued', 'delivered', 'failed', 'skipped');
+export const WebhookPeriod = Schema.Literal('day', 'week', 'month');
+// ── Config ─────────────────────────────────────────────────────────────────
+export const WebhookEnvironment = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    webhookUrl: Schema.NullOr(Schema.String),
+    hasSecret: Schema.Boolean,
+    updatedAt: Schema.String,
+});
+export const ProjectRef = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    slug: Schema.String,
+});
+export const GetWebhookConfigResult = Schema.Struct({
+    app: ProjectRef,
+    environments: Schema.Array(WebhookEnvironment),
+    supportedEvents: Schema.Array(Schema.String),
+});
+export const UpdateWebhookConfigInput = Schema.Struct({
+    environmentId: Schema.String,
+    webhookUrl: Schema.NullOr(Schema.String),
+    regenerateSecret: Schema.optional(Schema.Boolean),
+});
+export const UpdateWebhookConfigResult = Schema.Struct({
+    success: Schema.Boolean,
+    webhookUrl: Schema.NullOr(Schema.String),
+    secretGenerated: Schema.Boolean,
+    webhookSecretPrefix: Schema.optional(Schema.String),
+});
+// ── Deliveries ─────────────────────────────────────────────────────────────
+export const WebhookDelivery = Schema.Struct({
+    id: Schema.String,
+    event: Schema.String,
+    url: Schema.String,
+    status: WebhookStatus,
+    retryCount: Schema.Number,
+    responseStatus: Schema.NullOr(Schema.Number),
+    error: Schema.NullOr(Schema.String),
+    createdAt: Schema.String,
+    queuedAt: Schema.NullOr(Schema.String),
+    deliveredAt: Schema.NullOr(Schema.String),
+    failedAt: Schema.NullOr(Schema.String),
+});
+export const WebhookDeliveryDetail = Schema.Struct({
+    id: Schema.String,
+    event: Schema.String,
+    url: Schema.String,
+    payload: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+    status: WebhookStatus,
+    messageId: Schema.NullOr(Schema.String),
+    responseStatus: Schema.NullOr(Schema.Number),
+    error: Schema.NullOr(Schema.String),
+    retryCount: Schema.Number,
+    createdAt: Schema.String,
+    queuedAt: Schema.NullOr(Schema.String),
+    deliveredAt: Schema.NullOr(Schema.String),
+    failedAt: Schema.NullOr(Schema.String),
+});
+export const ListWebhookDeliveriesQuery = Schema.Struct({
+    status: Schema.optional(WebhookStatus),
+    event: Schema.optional(Schema.String),
+    limit: Schema.optional(Schema.String),
+    offset: Schema.optional(Schema.String),
+    environmentId: Schema.optional(Schema.String),
+});
+export const ListWebhookDeliveriesResult = Schema.Struct({
+    deliveries: Schema.Array(WebhookDelivery),
+    total: Schema.Number,
+    limit: Schema.Number,
+    offset: Schema.Number,
+});
+export const ReplayDeliveryResult = Schema.Struct({
+    success: Schema.Boolean,
+    newDeliveryId: Schema.NullOr(Schema.String),
+    messageId: Schema.NullOr(Schema.String),
+});
+export const FailedDeliveriesQuery = Schema.Struct({
+    limit: Schema.optional(Schema.String),
+});
+export const FailedDelivery = Schema.Struct({
+    id: Schema.String,
+    event: Schema.String,
+    url: Schema.String,
+    error: Schema.NullOr(Schema.String),
+    retryCount: Schema.Number,
+    createdAt: Schema.String,
+    failedAt: Schema.NullOr(Schema.String),
+});
+export const FailedDeliveriesResult = Schema.Struct({
+    deliveries: Schema.Array(FailedDelivery),
+    total: Schema.Number,
+});
+// ── Stats ──────────────────────────────────────────────────────────────────
+export const WebhookStatsQuery = Schema.Struct({
+    period: Schema.optional(WebhookPeriod),
+});
+export const WebhookStatsResult = Schema.Struct({
+    period: WebhookPeriod,
+    totals: Schema.Struct({
+        total: Schema.Number,
+        delivered: Schema.Number,
+        failed: Schema.Number,
+        pending: Schema.Number,
+        deliveryRate: Schema.Number,
+    }),
+    byEvent: Schema.Array(Schema.Struct({
+        event: Schema.String,
+        count: Schema.Number,
+    })),
+    byStatus: Schema.Array(Schema.Struct({
+        status: WebhookStatus,
+        count: Schema.Number,
+    })),
+});
+// ── Admin (super-admin) ────────────────────────────────────────────────────
+export const WebhooksAdminOverviewResult = Schema.Struct({
+    period: WebhookPeriod,
+    totals: Schema.Struct({
+        total: Schema.Number,
+        delivered: Schema.Number,
+        failed: Schema.Number,
+        pending: Schema.Number,
+        deliveryRate: Schema.Number,
+    }),
+    byProject: Schema.Array(Schema.Struct({
+        projectId: Schema.String,
+        projectName: Schema.String,
+        total: Schema.Number,
+        delivered: Schema.Number,
+        failed: Schema.Number,
+        deliveryRate: Schema.Number,
+    })),
+    byEvent: Schema.Array(Schema.Struct({
+        event: Schema.String,
+        count: Schema.Number,
+    })),
+    recentFailures: Schema.Array(Schema.Struct({
+        id: Schema.String,
+        projectId: Schema.String,
+        projectName: Schema.String,
+        event: Schema.String,
+        url: Schema.String,
+        error: Schema.NullOr(Schema.String),
+        retryCount: Schema.Number,
+        responseStatus: Schema.NullOr(Schema.Number),
+        timestamp: Schema.String,
+        failedAt: Schema.NullOr(Schema.String),
+    })),
+});
+export const AdminProjectDeliveriesQuery = Schema.Struct({
+    status: Schema.optional(WebhookStatus),
+    limit: Schema.optional(Schema.String),
+});
+export const AdminProjectDeliveryItem = Schema.Struct({
+    id: Schema.String,
+    event: Schema.String,
+    url: Schema.String,
+    status: WebhookStatus,
+    retryCount: Schema.Number,
+    responseStatus: Schema.NullOr(Schema.Number),
+    error: Schema.NullOr(Schema.String),
+    timestamp: Schema.String,
+    queuedAt: Schema.NullOr(Schema.String),
+    deliveredAt: Schema.NullOr(Schema.String),
+    failedAt: Schema.NullOr(Schema.String),
+});
+export const AdminProjectDeliveriesResult = Schema.Array(AdminProjectDeliveryItem);
+export const BulkReplayInput = Schema.Struct({
+    projectId: Schema.String,
+    deliveryIds: Schema.optional(Schema.Array(Schema.String)),
+    limit: Schema.optional(Schema.Number),
+});
+export const BulkReplayResult = Schema.Struct({
+    total: Schema.Number,
+    succeeded: Schema.Number,
+    failed: Schema.Number,
+    errors: Schema.optional(Schema.Array(Schema.Struct({
+        deliveryId: Schema.String,
+        error: Schema.String,
+    }))),
+});

package/package.json

@@ -0,0 +1,154 @@
+{
+	"name": "@sylphx/contract",
+	"version": "0.2.0",
+	"description": "Sylphx Platform contract — Effect Schema SSOT for every API endpoint (ADR-084).",
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"homepage": "https://sylphx.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/SylphxAI/platform.git",
+		"directory": "packages/contract"
+	},
+	"bugs": {
+		"url": "https://github.com/SylphxAI/platform/issues"
+	},
+	"author": "Sylphx",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./endpoint": {
+			"import": "./dist/endpoint.js",
+			"types": "./dist/endpoint.d.ts"
+		},
+		"./errors": {
+			"import": "./dist/errors.js",
+			"types": "./dist/errors.d.ts"
+		},
+		"./schemas/project": {
+			"import": "./dist/schemas/project.js",
+			"types": "./dist/schemas/project.d.ts"
+		},
+		"./schemas/deployment": {
+			"import": "./dist/schemas/deployment.js",
+			"types": "./dist/schemas/deployment.d.ts"
+		},
+		"./schemas/environment": {
+			"import": "./dist/schemas/environment.js",
+			"types": "./dist/schemas/environment.d.ts"
+		},
+		"./schemas/database": {
+			"import": "./dist/schemas/database.js",
+			"types": "./dist/schemas/database.d.ts"
+		},
+		"./schemas/env-var": {
+			"import": "./dist/schemas/env-var.js",
+			"types": "./dist/schemas/env-var.d.ts"
+		},
+		"./schemas/domain": {
+			"import": "./dist/schemas/domain.js",
+			"types": "./dist/schemas/domain.d.ts"
+		},
+		"./schemas/user": {
+			"import": "./dist/schemas/user.js",
+			"types": "./dist/schemas/user.d.ts"
+		},
+		"./schemas/organization": {
+			"import": "./dist/schemas/organization.js",
+			"types": "./dist/schemas/organization.d.ts"
+		},
+		"./schemas/secret": {
+			"import": "./dist/schemas/secret.js",
+			"types": "./dist/schemas/secret.d.ts"
+		},
+		"./schemas/auth": {
+			"import": "./dist/schemas/auth.js",
+			"types": "./dist/schemas/auth.d.ts"
+		},
+		"./schemas/ids": {
+			"import": "./dist/schemas/ids.js",
+			"types": "./dist/schemas/ids.d.ts"
+		},
+		"./endpoints/projects": {
+			"import": "./dist/endpoints/projects.js",
+			"types": "./dist/endpoints/projects.d.ts"
+		},
+		"./endpoints/deployments": {
+			"import": "./dist/endpoints/deployments.js",
+			"types": "./dist/endpoints/deployments.d.ts"
+		},
+		"./endpoints/environments": {
+			"import": "./dist/endpoints/environments.js",
+			"types": "./dist/endpoints/environments.d.ts"
+		},
+		"./endpoints/databases": {
+			"import": "./dist/endpoints/databases.js",
+			"types": "./dist/endpoints/databases.d.ts"
+		},
+		"./endpoints/env-vars": {
+			"import": "./dist/endpoints/env-vars.js",
+			"types": "./dist/endpoints/env-vars.d.ts"
+		},
+		"./endpoints/domains": {
+			"import": "./dist/endpoints/domains.js",
+			"types": "./dist/endpoints/domains.d.ts"
+		},
+		"./endpoints/users": {
+			"import": "./dist/endpoints/users.js",
+			"types": "./dist/endpoints/users.d.ts"
+		},
+		"./endpoints/organizations": {
+			"import": "./dist/endpoints/organizations.js",
+			"types": "./dist/endpoints/organizations.d.ts"
+		},
+		"./endpoints/secrets": {
+			"import": "./dist/endpoints/secrets.js",
+			"types": "./dist/endpoints/secrets.d.ts"
+		},
+		"./endpoints/auth": {
+			"import": "./dist/endpoints/auth.js",
+			"types": "./dist/endpoints/auth.d.ts"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"dev": "tsc --watch",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"prepublishOnly": "bun run build"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"sylphx",
+		"contract",
+		"effect-schema",
+		"standard-schema",
+		"paas",
+		"typescript",
+		"openapi"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"effect": ">=3.21.0"
+	},
+	"devDependencies": {
+		"effect": "3.21.0",
+		"typescript": "^5.9.0"
+	}
+}