@sylphx/contract 0.2.0

package/dist/endpoints/webhooks.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Webhooks endpoints — Console-plane outgoing webhook config + delivery log
+ * + stats + replays + super-admin cross-project operations. Distinct from
+ * runtime webhook signature verification (that lives in `@sylphx/sdk/server`
+ * as a helper library, not a Platform API).
+ *
+ * Production mount: `/webhooks/*` (see
+ * `apps/api/src/server/platform/app.ts`).
+ *
+ * Plane mix:
+ *   - `management` — per-project config / deliveries / stats
+ *   - `admin`      — `/admin/*` super-admin cross-project overview + bulk replay
+ */
+import { Schema } from 'effect';
+export declare const webhooksEndpoints: {
+    readonly getConfig: import("../endpoint.js").Endpoint<"GET", "/webhooks/projects/:id", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        app: Schema.Struct<{
+            id: typeof Schema.String;
+            name: typeof Schema.String;
+            slug: typeof Schema.String;
+        }>;
+        environments: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            name: typeof Schema.String;
+            webhookUrl: Schema.NullOr<typeof Schema.String>;
+            hasSecret: typeof Schema.Boolean;
+            updatedAt: typeof Schema.String;
+        }>>;
+        supportedEvents: Schema.Array$<typeof Schema.String>;
+    }>>;
+    readonly updateConfig: import("../endpoint.js").Endpoint<"PATCH", "/webhooks/projects/:id", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        environmentId: typeof Schema.String;
+        webhookUrl: Schema.NullOr<typeof Schema.String>;
+        regenerateSecret: Schema.optional<typeof Schema.Boolean>;
+    }>, Schema.Struct<{
+        success: typeof Schema.Boolean;
+        webhookUrl: Schema.NullOr<typeof Schema.String>;
+        secretGenerated: typeof Schema.Boolean;
+        webhookSecretPrefix: Schema.optional<typeof Schema.String>;
+    }>>;
+    readonly listDeliveries: import("../endpoint.js").Endpoint<"GET", "/webhooks/projects/:id/deliveries", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Struct<{
+        status: Schema.optional<Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>>;
+        event: Schema.optional<typeof Schema.String>;
+        limit: Schema.optional<typeof Schema.String>;
+        offset: Schema.optional<typeof Schema.String>;
+        environmentId: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        deliveries: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            event: typeof Schema.String;
+            url: typeof Schema.String;
+            status: Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>;
+            retryCount: typeof Schema.Number;
+            responseStatus: Schema.NullOr<typeof Schema.Number>;
+            error: Schema.NullOr<typeof Schema.String>;
+            createdAt: typeof Schema.String;
+            queuedAt: Schema.NullOr<typeof Schema.String>;
+            deliveredAt: Schema.NullOr<typeof Schema.String>;
+            failedAt: Schema.NullOr<typeof Schema.String>;
+        }>>;
+        total: typeof Schema.Number;
+        limit: typeof Schema.Number;
+        offset: typeof Schema.Number;
+    }>>;
+    readonly failedDeliveries: import("../endpoint.js").Endpoint<"GET", "/webhooks/projects/:id/failed", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Struct<{
+        limit: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        deliveries: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            event: typeof Schema.String;
+            url: typeof Schema.String;
+            error: Schema.NullOr<typeof Schema.String>;
+            retryCount: typeof Schema.Number;
+            createdAt: typeof Schema.String;
+            failedAt: Schema.NullOr<typeof Schema.String>;
+        }>>;
+        total: typeof Schema.Number;
+    }>>;
+    readonly getDelivery: import("../endpoint.js").Endpoint<"GET", "/webhooks/:webhookId", Schema.Struct<{
+        webhookId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        id: typeof Schema.String;
+        event: typeof Schema.String;
+        url: typeof Schema.String;
+        payload: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        status: Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>;
+        messageId: Schema.NullOr<typeof Schema.String>;
+        responseStatus: Schema.NullOr<typeof Schema.Number>;
+        error: Schema.NullOr<typeof Schema.String>;
+        retryCount: typeof Schema.Number;
+        createdAt: typeof Schema.String;
+        queuedAt: Schema.NullOr<typeof Schema.String>;
+        deliveredAt: Schema.NullOr<typeof Schema.String>;
+        failedAt: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    readonly replayDelivery: import("../endpoint.js").Endpoint<"POST", "/webhooks/:webhookId/replay", Schema.Struct<{
+        webhookId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        success: typeof Schema.Boolean;
+        newDeliveryId: Schema.NullOr<typeof Schema.String>;
+        messageId: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    readonly getStats: import("../endpoint.js").Endpoint<"GET", "/webhooks/projects/:id/stats", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Struct<{
+        period: Schema.optional<Schema.Literal<["day", "week", "month"]>>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        period: Schema.Literal<["day", "week", "month"]>;
+        totals: Schema.Struct<{
+            total: typeof Schema.Number;
+            delivered: typeof Schema.Number;
+            failed: typeof Schema.Number;
+            pending: typeof Schema.Number;
+            deliveryRate: typeof Schema.Number;
+        }>;
+        byEvent: Schema.Array$<Schema.Struct<{
+            event: typeof Schema.String;
+            count: typeof Schema.Number;
+        }>>;
+        byStatus: Schema.Array$<Schema.Struct<{
+            status: Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>;
+            count: typeof Schema.Number;
+        }>>;
+    }>>;
+    readonly adminOverview: import("../endpoint.js").Endpoint<"GET", "/webhooks/admin/overview", Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        period: Schema.optional<Schema.Literal<["day", "week", "month"]>>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        period: Schema.Literal<["day", "week", "month"]>;
+        totals: Schema.Struct<{
+            total: typeof Schema.Number;
+            delivered: typeof Schema.Number;
+            failed: typeof Schema.Number;
+            pending: typeof Schema.Number;
+            deliveryRate: typeof Schema.Number;
+        }>;
+        byProject: Schema.Array$<Schema.Struct<{
+            projectId: typeof Schema.String;
+            projectName: typeof Schema.String;
+            total: typeof Schema.Number;
+            delivered: typeof Schema.Number;
+            failed: typeof Schema.Number;
+            deliveryRate: typeof Schema.Number;
+        }>>;
+        byEvent: Schema.Array$<Schema.Struct<{
+            event: typeof Schema.String;
+            count: typeof Schema.Number;
+        }>>;
+        recentFailures: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            projectId: typeof Schema.String;
+            projectName: typeof Schema.String;
+            event: typeof Schema.String;
+            url: typeof Schema.String;
+            error: Schema.NullOr<typeof Schema.String>;
+            retryCount: typeof Schema.Number;
+            responseStatus: Schema.NullOr<typeof Schema.Number>;
+            timestamp: typeof Schema.String;
+            failedAt: Schema.NullOr<typeof Schema.String>;
+        }>>;
+    }>>;
+    readonly adminProjectDeliveries: import("../endpoint.js").Endpoint<"GET", "/webhooks/admin/projects/:projectId/deliveries", Schema.Struct<{
+        projectId: typeof Schema.String;
+    }>, Schema.Struct<{
+        status: Schema.optional<Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>>;
+        limit: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        event: typeof Schema.String;
+        url: typeof Schema.String;
+        status: Schema.Literal<["pending", "queued", "delivered", "failed", "skipped"]>;
+        retryCount: typeof Schema.Number;
+        responseStatus: Schema.NullOr<typeof Schema.Number>;
+        error: Schema.NullOr<typeof Schema.String>;
+        timestamp: typeof Schema.String;
+        queuedAt: Schema.NullOr<typeof Schema.String>;
+        deliveredAt: Schema.NullOr<typeof Schema.String>;
+        failedAt: Schema.NullOr<typeof Schema.String>;
+    }>>>;
+    readonly adminBulkReplay: import("../endpoint.js").Endpoint<"POST", "/webhooks/admin/bulk-replay", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        projectId: typeof Schema.String;
+        deliveryIds: Schema.optional<Schema.Array$<typeof Schema.String>>;
+        limit: Schema.optional<typeof Schema.Number>;
+    }>, Schema.Struct<{
+        total: typeof Schema.Number;
+        succeeded: typeof Schema.Number;
+        failed: typeof Schema.Number;
+        errors: Schema.optional<Schema.Array$<Schema.Struct<{
+            deliveryId: typeof Schema.String;
+            error: typeof Schema.String;
+        }>>>;
+    }>>;
+};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/endpoints/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/endpoints/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAyB/B,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGpB,CAAA"}

package/dist/endpoints/webhooks.js

@@ -0,0 +1,120 @@
+/**
+ * Webhooks endpoints — Console-plane outgoing webhook config + delivery log
+ * + stats + replays + super-admin cross-project operations. Distinct from
+ * runtime webhook signature verification (that lives in `@sylphx/sdk/server`
+ * as a helper library, not a Platform API).
+ *
+ * Production mount: `/webhooks/*` (see
+ * `apps/api/src/server/platform/app.ts`).
+ *
+ * Plane mix:
+ *   - `management` — per-project config / deliveries / stats
+ *   - `admin`      — `/admin/*` super-admin cross-project overview + bulk replay
+ */
+import { Schema } from 'effect';
+import { defineEndpoint } from '../endpoint.js';
+import { AdminProjectDeliveriesQuery, AdminProjectDeliveriesResult, BulkReplayInput, BulkReplayResult, FailedDeliveriesQuery, FailedDeliveriesResult, GetWebhookConfigResult, ListWebhookDeliveriesQuery, ListWebhookDeliveriesResult, ReplayDeliveryResult, UpdateWebhookConfigInput, UpdateWebhookConfigResult, WebhookDeliveryDetail, WebhookStatsQuery, WebhookStatsResult, WebhooksAdminOverviewResult, } from '../schemas/webhooks.js';
+const ProjectPath = Schema.Struct({ id: Schema.String });
+const WebhookIdPath = Schema.Struct({ webhookId: Schema.String });
+const AdminProjectIdPath = Schema.Struct({ projectId: Schema.String });
+export const webhooksEndpoints = {
+    // ── Config ─────────────────────────────────────────────────────────────
+    getConfig: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/projects/:id',
+        params: ProjectPath,
+        response: GetWebhookConfigResult,
+        plane: 'management',
+        summary: 'Get webhook configuration for a project',
+        tags: ['webhooks'],
+    }),
+    updateConfig: defineEndpoint({
+        method: 'PATCH',
+        path: '/webhooks/projects/:id',
+        params: ProjectPath,
+        body: UpdateWebhookConfigInput,
+        response: UpdateWebhookConfigResult,
+        plane: 'management',
+        summary: 'Update webhook URL or regenerate secret for an environment',
+        tags: ['webhooks'],
+    }),
+    // ── Deliveries ─────────────────────────────────────────────────────────
+    listDeliveries: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/projects/:id/deliveries',
+        params: ProjectPath,
+        query: ListWebhookDeliveriesQuery,
+        response: ListWebhookDeliveriesResult,
+        plane: 'management',
+        summary: 'List webhook deliveries for a project',
+        tags: ['webhooks'],
+    }),
+    failedDeliveries: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/projects/:id/failed',
+        params: ProjectPath,
+        query: FailedDeliveriesQuery,
+        response: FailedDeliveriesResult,
+        plane: 'management',
+        summary: 'Get replayable failed deliveries for a project',
+        tags: ['webhooks'],
+    }),
+    getDelivery: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/:webhookId',
+        params: WebhookIdPath,
+        response: WebhookDeliveryDetail,
+        plane: 'management',
+        summary: 'Get a webhook delivery with full payload',
+        tags: ['webhooks'],
+    }),
+    replayDelivery: defineEndpoint({
+        method: 'POST',
+        path: '/webhooks/:webhookId/replay',
+        params: WebhookIdPath,
+        response: ReplayDeliveryResult,
+        plane: 'management',
+        summary: 'Replay a failed webhook delivery',
+        tags: ['webhooks'],
+    }),
+    // ── Stats ──────────────────────────────────────────────────────────────
+    getStats: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/projects/:id/stats',
+        params: ProjectPath,
+        query: WebhookStatsQuery,
+        response: WebhookStatsResult,
+        plane: 'management',
+        summary: 'Webhook delivery statistics for a project',
+        tags: ['webhooks'],
+    }),
+    // ── Admin (super-admin cross-project) ──────────────────────────────────
+    adminOverview: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/admin/overview',
+        query: WebhookStatsQuery,
+        response: WebhooksAdminOverviewResult,
+        plane: 'admin',
+        summary: 'Cross-project webhook delivery overview (super-admin only)',
+        tags: ['webhooks-admin'],
+    }),
+    adminProjectDeliveries: defineEndpoint({
+        method: 'GET',
+        path: '/webhooks/admin/projects/:projectId/deliveries',
+        params: AdminProjectIdPath,
+        query: AdminProjectDeliveriesQuery,
+        response: AdminProjectDeliveriesResult,
+        plane: 'admin',
+        summary: 'Per-project delivery log (super-admin only)',
+        tags: ['webhooks-admin'],
+    }),
+    adminBulkReplay: defineEndpoint({
+        method: 'POST',
+        path: '/webhooks/admin/bulk-replay',
+        body: BulkReplayInput,
+        response: BulkReplayResult,
+        plane: 'admin',
+        summary: 'Bulk replay failed webhook deliveries (super-admin only)',
+        tags: ['webhooks-admin'],
+    }),
+};

package/dist/errors.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Tagged error envelopes — the shape every API failure serialises to.
+ *
+ * The Sylphx API normalises failures to RFC-7807-adjacent JSON bodies. We
+ * model them as tagged Effect Schemas so handlers (server-side Effects) and
+ * consumers (SDKs) can discriminate on `_tag` and derive typed failure
+ * unions without any string comparison on `code`.
+ */
+import { Schema } from 'effect';
+/** 400 — request failed validation. */
+export declare const BadRequestError: Schema.Struct<{
+    _tag: Schema.Literal<["BadRequest"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    details: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type BadRequestError = typeof BadRequestError.Type;
+/** 401 — no valid credentials supplied. */
+export declare const UnauthorizedError: Schema.Struct<{
+    _tag: Schema.Literal<["Unauthorized"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type UnauthorizedError = typeof UnauthorizedError.Type;
+/** 403 — credentials valid but caller not permitted. */
+export declare const ForbiddenError: Schema.Struct<{
+    _tag: Schema.Literal<["Forbidden"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type ForbiddenError = typeof ForbiddenError.Type;
+/** 404 — target entity does not exist or is not visible to caller. */
+export declare const NotFoundError: Schema.Struct<{
+    _tag: Schema.Literal<["NotFound"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type NotFoundError = typeof NotFoundError.Type;
+/** 409 — request conflicts with current state (uniqueness, optimistic lock, etc.). */
+export declare const ConflictError: Schema.Struct<{
+    _tag: Schema.Literal<["Conflict"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type ConflictError = typeof ConflictError.Type;
+/** 422 — semantic validation failure (well-formed but unacceptable). */
+export declare const UnprocessableEntityError: Schema.Struct<{
+    _tag: Schema.Literal<["UnprocessableEntity"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    details: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type UnprocessableEntityError = typeof UnprocessableEntityError.Type;
+/** 429 — rate-limited. */
+export declare const RateLimitedError: Schema.Struct<{
+    _tag: Schema.Literal<["RateLimited"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    retryAfterSeconds: Schema.optional<typeof Schema.Number>;
+}>;
+export type RateLimitedError = typeof RateLimitedError.Type;
+/** 500 — unexpected server-side failure. */
+export declare const InternalServerError: Schema.Struct<{
+    _tag: Schema.Literal<["InternalServer"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type InternalServerError = typeof InternalServerError.Type;
+/** Union of every standard error envelope — convenient for generic handlers. */
+export declare const ApiError: Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["BadRequest"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    details: Schema.optional<typeof Schema.Unknown>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["Unauthorized"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["Forbidden"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["NotFound"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["Conflict"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["UnprocessableEntity"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    details: Schema.optional<typeof Schema.Unknown>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["RateLimited"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    retryAfterSeconds: Schema.optional<typeof Schema.Number>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["InternalServer"]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+}>]>;
+export type ApiError = typeof ApiError.Type;
+/** Default error map — attach to endpoints that only care about the common shapes. */
+export declare const commonErrors: {
+    readonly 400: Schema.Struct<{
+        _tag: Schema.Literal<["BadRequest"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+        details: Schema.optional<typeof Schema.Unknown>;
+    }>;
+    readonly 401: Schema.Struct<{
+        _tag: Schema.Literal<["Unauthorized"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly 403: Schema.Struct<{
+        _tag: Schema.Literal<["Forbidden"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly 404: Schema.Struct<{
+        _tag: Schema.Literal<["NotFound"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly 409: Schema.Struct<{
+        _tag: Schema.Literal<["Conflict"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly 422: Schema.Struct<{
+        _tag: Schema.Literal<["UnprocessableEntity"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+        details: Schema.optional<typeof Schema.Unknown>;
+    }>;
+    readonly 429: Schema.Struct<{
+        _tag: Schema.Literal<["RateLimited"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+        retryAfterSeconds: Schema.optional<typeof Schema.Number>;
+    }>;
+    readonly 500: Schema.Struct<{
+        _tag: Schema.Literal<["InternalServer"]>;
+        code: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,uCAAuC;AACvC,eAAO,MAAM,eAAe;;;;;EAK1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB;;;;EAI5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D,wDAAwD;AACxD,eAAO,MAAM,cAAc;;;;EAIzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,sEAAsE;AACtE,eAAO,MAAM,aAAa;;;;EAIxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD,sFAAsF;AACtF,eAAO,MAAM,aAAa;;;;EAIxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD,wEAAwE;AACxE,eAAO,MAAM,wBAAwB;;;;;EAKnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,IAAI,CAAA;AAE3E,0BAA0B;AAC1B,eAAO,MAAM,gBAAgB;;;;;EAK3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE,gFAAgF;AAChF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IASpB,CAAA;AACD,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C,sFAAsF;AACtF,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CASf,CAAA"}

package/dist/errors.js

@@ -0,0 +1,73 @@
+/**
+ * Tagged error envelopes — the shape every API failure serialises to.
+ *
+ * The Sylphx API normalises failures to RFC-7807-adjacent JSON bodies. We
+ * model them as tagged Effect Schemas so handlers (server-side Effects) and
+ * consumers (SDKs) can discriminate on `_tag` and derive typed failure
+ * unions without any string comparison on `code`.
+ */
+import { Schema } from 'effect';
+/** 400 — request failed validation. */
+export const BadRequestError = Schema.Struct({
+    _tag: Schema.Literal('BadRequest'),
+    code: Schema.String,
+    message: Schema.String,
+    details: Schema.optional(Schema.Unknown),
+});
+/** 401 — no valid credentials supplied. */
+export const UnauthorizedError = Schema.Struct({
+    _tag: Schema.Literal('Unauthorized'),
+    code: Schema.String,
+    message: Schema.String,
+});
+/** 403 — credentials valid but caller not permitted. */
+export const ForbiddenError = Schema.Struct({
+    _tag: Schema.Literal('Forbidden'),
+    code: Schema.String,
+    message: Schema.String,
+});
+/** 404 — target entity does not exist or is not visible to caller. */
+export const NotFoundError = Schema.Struct({
+    _tag: Schema.Literal('NotFound'),
+    code: Schema.String,
+    message: Schema.String,
+});
+/** 409 — request conflicts with current state (uniqueness, optimistic lock, etc.). */
+export const ConflictError = Schema.Struct({
+    _tag: Schema.Literal('Conflict'),
+    code: Schema.String,
+    message: Schema.String,
+});
+/** 422 — semantic validation failure (well-formed but unacceptable). */
+export const UnprocessableEntityError = Schema.Struct({
+    _tag: Schema.Literal('UnprocessableEntity'),
+    code: Schema.String,
+    message: Schema.String,
+    details: Schema.optional(Schema.Unknown),
+});
+/** 429 — rate-limited. */
+export const RateLimitedError = Schema.Struct({
+    _tag: Schema.Literal('RateLimited'),
+    code: Schema.String,
+    message: Schema.String,
+    retryAfterSeconds: Schema.optional(Schema.Number),
+});
+/** 500 — unexpected server-side failure. */
+export const InternalServerError = Schema.Struct({
+    _tag: Schema.Literal('InternalServer'),
+    code: Schema.String,
+    message: Schema.String,
+});
+/** Union of every standard error envelope — convenient for generic handlers. */
+export const ApiError = Schema.Union(BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitedError, InternalServerError);
+/** Default error map — attach to endpoints that only care about the common shapes. */
+export const commonErrors = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitedError,
+    500: InternalServerError,
+};