@prave/shared 1.4.2 → 1.4.3

package/dist/schemas/index.d.ts

@@ -15,4 +15,8 @@ export * from './intelligence.schema.js';
 export * from './api-keys.schema.js';
 export * from './skill-report.schema.js';
 export * from './run.schema.js';
+export * from './vault.schema.js';
+export * from './kv.schema.js';
+export * from './webhook-endpoint.schema.js';
+export * from './sdk.schema.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iBAAiB,CAAA"}

package/dist/schemas/index.js

@@ -15,3 +15,7 @@ export * from './intelligence.schema.js';
 export * from './api-keys.schema.js';
 export * from './skill-report.schema.js';
 export * from './run.schema.js';
+export * from './vault.schema.js';
+export * from './kv.schema.js';
+export * from './webhook-endpoint.schema.js';
+export * from './sdk.schema.js';

package/dist/schemas/kv.schema.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * KV — per-run persistent key/value store, encrypted at rest.
+ *
+ * Lives in the `run_kv` table. Each row is scoped to a single `run_id`;
+ * RLS for dashboard reads, JWT-scoped service-role for SDK reads.
+ *
+ * Designed for the canonical "skill exchanged OAuth code → access token,
+ * stashes it for the next cron tick" pattern. Values are opaque blobs
+ * (we don't introspect them); 64KB per value, optional TTL.
+ */
+export declare const kvKeySchema: z.ZodString;
+export type KvKey = z.infer<typeof kvKeySchema>;
+export declare const kvEntrySchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    size_bytes: z.ZodNumber;
+    expires_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    size_bytes: number;
+    updated_at: string;
+    expires_at: string | null;
+    key: string;
+}, {
+    value: string;
+    size_bytes: number;
+    updated_at: string;
+    expires_at: string | null;
+    key: string;
+}>;
+export type KvEntry = z.infer<typeof kvEntrySchema>;
+export declare const kvPutInputSchema: z.ZodObject<{
+    value: z.ZodString;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    ttl_seconds?: number | undefined;
+}, {
+    value: string;
+    ttl_seconds?: number | undefined;
+}>;
+export type KvPutInput = z.infer<typeof kvPutInputSchema>;
+export declare const kvListQuerySchema: z.ZodObject<{
+    prefix: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    prefix?: string | undefined;
+}, {
+    limit?: number | undefined;
+    prefix?: string | undefined;
+}>;
+export type KvListQuery = z.infer<typeof kvListQuerySchema>;
+//# sourceMappingURL=kv.schema.d.ts.map

package/dist/schemas/kv.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/kv.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;GASG;AAMH,eAAO,MAAM,WAAW,aAOrB,CAAA;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAE/C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;EAMxB,CAAA;AACF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAKnD,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAGzD,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA"}

package/dist/schemas/kv.schema.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+/**
+ * KV — per-run persistent key/value store, encrypted at rest.
+ *
+ * Lives in the `run_kv` table. Each row is scoped to a single `run_id`;
+ * RLS for dashboard reads, JWT-scoped service-role for SDK reads.
+ *
+ * Designed for the canonical "skill exchanged OAuth code → access token,
+ * stashes it for the next cron tick" pattern. Values are opaque blobs
+ * (we don't introspect them); 64KB per value, optional TTL.
+ */
+// Same shape as a URL path-segment with a few "scoped" delimiters so
+// skills can build namespaces (`oauth:tiktok:state`, `queue:pending`).
+// We keep it permissive enough not to surprise users; the colon /
+// dash / dot are common across all KV ecosystems.
+export const kvKeySchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z0-9_\-.:]+$/, 'Letters, digits, and any of `_ - . :` — no spaces or slashes.');
+export const kvEntrySchema = z.object({
+    key: kvKeySchema,
+    value: z.string(),
+    size_bytes: z.number().int().nonnegative(),
+    expires_at: z.string().datetime().nullable(),
+    updated_at: z.string().datetime(),
+});
+// Body for PUT /api/v1/sdk/kv/:key (the SDK route) and PUT
+// /api/v1/runs/:slug/kv/:key (the dashboard debug route). ttlSeconds
+// translates to expires_at = now() + ttlSeconds in the service layer.
+export const kvPutInputSchema = z.object({
+    value: z.string().max(65_536),
+    ttl_seconds: z.number().int().positive().max(60 * 60 * 24 * 365).optional(),
+});
+// GET list filter — prefix is the only filter supported.
+export const kvListQuerySchema = z.object({
+    prefix: z.string().max(256).optional(),
+    limit: z.number().int().min(1).max(1_000).default(100).optional(),
+});

package/dist/schemas/sdk.schema.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+/**
+ * Shapes for the authenticated SDK surface mounted at `/api/v1/sdk/*`.
+ *
+ * Auth: middleware verifies a HS256 JWT passed as Bearer in the
+ * `PRAVE_SDK_TOKEN` env var inside the bwrap sandbox. Claims fall into
+ * the shape below, which is also what `sdkAuth` attaches to `req`.
+ *
+ * Every SDK request resolves to a single run_id; the rest of the
+ * surface is scoped accordingly (no cross-run reads).
+ */
+export declare const sdkTokenClaimsSchema: z.ZodObject<{
+    run_id: z.ZodString;
+    exec_id: z.ZodString;
+    exp: z.ZodNumber;
+    iat: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    run_id: string;
+    exec_id: string;
+    exp: number;
+    iat?: number | undefined;
+}, {
+    run_id: string;
+    exec_id: string;
+    exp: number;
+    iat?: number | undefined;
+}>;
+export type SdkTokenClaims = z.infer<typeof sdkTokenClaimsSchema>;
+export declare const sdkLogInputSchema: z.ZodObject<{
+    level: z.ZodEnum<["debug", "info", "warn", "error"]>;
+    message: z.ZodString;
+    context: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>, Record<string, unknown> | undefined, Record<string, unknown> | undefined>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    level: "error" | "debug" | "info" | "warn";
+    context?: Record<string, unknown> | undefined;
+}, {
+    message: string;
+    level: "error" | "debug" | "info" | "warn";
+    context?: Record<string, unknown> | undefined;
+}>;
+export type SdkLogInput = z.infer<typeof sdkLogInputSchema>;
+export declare const sdkWebhooksAckInputSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    ids: string[];
+}, {
+    ids: string[];
+}>;
+export type SdkWebhooksAckInput = z.infer<typeof sdkWebhooksAckInputSchema>;
+//# sourceMappingURL=sdk.schema.d.ts.map

package/dist/schemas/sdk.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/sdk.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;GASG;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAO/B,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAIjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAW5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAK3D,eAAO,MAAM,yBAAyB;;;;;;EAEpC,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA"}

package/dist/schemas/sdk.schema.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * Shapes for the authenticated SDK surface mounted at `/api/v1/sdk/*`.
+ *
+ * Auth: middleware verifies a HS256 JWT passed as Bearer in the
+ * `PRAVE_SDK_TOKEN` env var inside the bwrap sandbox. Claims fall into
+ * the shape below, which is also what `sdkAuth` attaches to `req`.
+ *
+ * Every SDK request resolves to a single run_id; the rest of the
+ * surface is scoped accordingly (no cross-run reads).
+ */
+export const sdkTokenClaimsSchema = z.object({
+    run_id: z.string().uuid(),
+    exec_id: z.string().uuid(),
+    // Standard JWT registered fields. `exp` is required, `iat` is convenient
+    // for debugging in logs but not enforced.
+    exp: z.number().int().positive(),
+    iat: z.number().int().positive().optional(),
+});
+// POST /api/v1/sdk/log — structured log line forwarded to
+// `run_executions.log_text` so it surfaces in the dashboard log viewer.
+export const sdkLogInputSchema = z.object({
+    level: z.enum(['debug', 'info', 'warn', 'error']),
+    message: z.string().max(8_192),
+    // Arbitrary structured context — must JSON-stringify under 4 KB.
+    context: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .refine((v) => v === undefined || JSON.stringify(v).length <= 4_096, 'context must serialise to under 4 KB'),
+});
+// POST /api/v1/sdk/webhooks/:endpointId/ack — body is `{ ids: [..] }`
+// or an empty body to ack the events implicitly returned in the prior
+// drain call (cookied via the SDK).
+export const sdkWebhooksAckInputSchema = z.object({
+    ids: z.array(z.string().uuid()).min(1).max(500),
+});

package/dist/schemas/vault.schema.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * Vault — user-supplied secrets bound to a Run.
+ *
+ * Values are AES-256-GCM-encrypted at rest (same master key as
+ * `runs.env_encrypted` and `user_api_keys`). The plaintext only ever
+ * surfaces to the worker via the `/api/v1/sdk/vault/:key` route, which
+ * authenticates with the short-lived `PRAVE_SDK_TOKEN` JWT minted per
+ * execution.
+ *
+ * Dashboard UI sets values; SDK reads them. There is intentionally no
+ * read endpoint that returns plaintext to the dashboard — once set, a
+ * value can only be overwritten, never read back through the web app.
+ */
+export declare const vaultKeySchema: z.ZodString;
+export type VaultKey = z.infer<typeof vaultKeySchema>;
+export declare const vaultSecretSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    link: z.ZodNullable<z.ZodString>;
+    size_bytes: z.ZodNumber;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    size_bytes: number;
+    created_at: string;
+    updated_at: string;
+    label: string | null;
+    key: string;
+    link: string | null;
+}, {
+    size_bytes: number;
+    created_at: string;
+    updated_at: string;
+    label: string | null;
+    key: string;
+    link: string | null;
+}>;
+export type VaultSecret = z.infer<typeof vaultSecretSchema>;
+export declare const vaultPutInputSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    label?: string | undefined;
+    link?: string | undefined;
+}, {
+    value: string;
+    label?: string | undefined;
+    link?: string | undefined;
+}>;
+export type VaultPutInput = z.infer<typeof vaultPutInputSchema>;
+//# sourceMappingURL=vault.schema.d.ts.map

package/dist/schemas/vault.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/vault.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;GAYG;AAMH,eAAO,MAAM,cAAc,aAOxB,CAAA;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAErD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAK3D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/schemas/vault.schema.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+/**
+ * Vault — user-supplied secrets bound to a Run.
+ *
+ * Values are AES-256-GCM-encrypted at rest (same master key as
+ * `runs.env_encrypted` and `user_api_keys`). The plaintext only ever
+ * surfaces to the worker via the `/api/v1/sdk/vault/:key` route, which
+ * authenticates with the short-lived `PRAVE_SDK_TOKEN` JWT minted per
+ * execution.
+ *
+ * Dashboard UI sets values; SDK reads them. There is intentionally no
+ * read endpoint that returns plaintext to the dashboard — once set, a
+ * value can only be overwritten, never read back through the web app.
+ */
+// POSIX-ish key — same shape as env var names so skill code can stash
+// secrets under the same identifier (`prave.vault.get('TIKTOK_CLIENT_ID')`)
+// or, where a skill expects an env var directly, the SDK's loader can
+// project them into the bwrap env without renaming.
+export const vaultKeySchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'Use POSIX-style names: letters, digits, underscore; cannot start with a digit.');
+export const vaultSecretSchema = z.object({
+    key: vaultKeySchema,
+    label: z.string().max(120).nullable(),
+    link: z.string().url().max(2_048).nullable(),
+    size_bytes: z.number().int().nonnegative(),
+    created_at: z.string().datetime(),
+    updated_at: z.string().datetime(),
+});
+// Body for PUT /api/v1/runs/:slug/vault/:key. Caller passes the full
+// new value; we encrypt + replace. Empty string is allowed (some
+// providers expect a literal "" header).
+export const vaultPutInputSchema = z.object({
+    value: z.string().max(65_536),
+    label: z.string().max(120).optional(),
+    link: z.string().url().max(2_048).optional(),
+});

package/dist/schemas/webhook-endpoint.schema.d.ts

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+/**
+ * Webhook endpoint declarations — each one mints a stable HTTPS URL on
+ * `in.prave.app/w/<runs.webhook_token>/<endpoint_id>` that buffers
+ * inbound traffic into `webhook_events` (or, when trigger_mode is
+ * 'immediate', also enqueues a fresh run execution).
+ *
+ * Two flavours of inbound traffic share this surface:
+ *   • short-lived OAuth callbacks (`?code=…&state=…`) — almost always
+ *     'immediate' so the code is exchanged before its ~10-minute window
+ *     closes;
+ *   • long-tail webhooks (Slack interactivity, TikTok post.published,
+ *     etc.) — 'buffer', drained by `prave.webhooks.drain()` on the
+ *     next cron run.
+ *
+ * HMAC verification is optional and only meaningful for buffered
+ * webhooks where the provider signs the body. OAuth callbacks rarely
+ * sign — providers rely on the redirect_uri being preregistered.
+ */
+export declare const webhookEndpointIdSchema: z.ZodString;
+export type WebhookEndpointId = z.infer<typeof webhookEndpointIdSchema>;
+export declare const webhookTriggerModeSchema: z.ZodEnum<["buffer", "immediate"]>;
+export type WebhookTriggerMode = z.infer<typeof webhookTriggerModeSchema>;
+export declare const webhookHmacAlgorithmSchema: z.ZodEnum<["sha256", "sha1", "sha512"]>;
+export type WebhookHmacAlgorithm = z.infer<typeof webhookHmacAlgorithmSchema>;
+export declare const webhookEndpointSchema: z.ZodObject<{
+    id: z.ZodString;
+    endpoint_id: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    url: z.ZodString;
+    hmac_header: z.ZodNullable<z.ZodString>;
+    hmac_algorithm: z.ZodNullable<z.ZodEnum<["sha256", "sha1", "sha512"]>>;
+    signing_secret_preview: z.ZodNullable<z.ZodString>;
+    trigger_mode: z.ZodEnum<["buffer", "immediate"]>;
+    response_status: z.ZodNumber;
+    response_body: z.ZodNullable<z.ZodString>;
+    response_content_type: z.ZodNullable<z.ZodString>;
+    events_30d: z.ZodOptional<z.ZodNumber>;
+    last_received_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    url: string;
+    label: string | null;
+    endpoint_id: string;
+    hmac_header: string | null;
+    hmac_algorithm: "sha256" | "sha1" | "sha512" | null;
+    signing_secret_preview: string | null;
+    trigger_mode: "buffer" | "immediate";
+    response_status: number;
+    response_body: string | null;
+    response_content_type: string | null;
+    events_30d?: number | undefined;
+    last_received_at?: string | null | undefined;
+}, {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    url: string;
+    label: string | null;
+    endpoint_id: string;
+    hmac_header: string | null;
+    hmac_algorithm: "sha256" | "sha1" | "sha512" | null;
+    signing_secret_preview: string | null;
+    trigger_mode: "buffer" | "immediate";
+    response_status: number;
+    response_body: string | null;
+    response_content_type: string | null;
+    events_30d?: number | undefined;
+    last_received_at?: string | null | undefined;
+}>;
+export type WebhookEndpoint = z.infer<typeof webhookEndpointSchema>;
+export declare const webhookEndpointCreateInputSchema: z.ZodObject<{
+    endpoint_id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    trigger_mode: z.ZodDefault<z.ZodEnum<["buffer", "immediate"]>>;
+    hmac_header: z.ZodOptional<z.ZodString>;
+    hmac_algorithm: z.ZodOptional<z.ZodEnum<["sha256", "sha1", "sha512"]>>;
+    signing_secret: z.ZodOptional<z.ZodString>;
+    response_status: z.ZodOptional<z.ZodNumber>;
+    response_body: z.ZodOptional<z.ZodString>;
+    response_content_type: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    endpoint_id: string;
+    trigger_mode: "buffer" | "immediate";
+    label?: string | undefined;
+    hmac_header?: string | undefined;
+    hmac_algorithm?: "sha256" | "sha1" | "sha512" | undefined;
+    response_status?: number | undefined;
+    response_body?: string | undefined;
+    response_content_type?: string | undefined;
+    signing_secret?: string | undefined;
+}, {
+    endpoint_id: string;
+    label?: string | undefined;
+    hmac_header?: string | undefined;
+    hmac_algorithm?: "sha256" | "sha1" | "sha512" | undefined;
+    trigger_mode?: "buffer" | "immediate" | undefined;
+    response_status?: number | undefined;
+    response_body?: string | undefined;
+    response_content_type?: string | undefined;
+    signing_secret?: string | undefined;
+}>;
+export type WebhookEndpointCreateInput = z.infer<typeof webhookEndpointCreateInputSchema>;
+export declare const webhookEndpointPatchInputSchema: z.ZodObject<Omit<{
+    endpoint_id: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    trigger_mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["buffer", "immediate"]>>>;
+    hmac_header: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    hmac_algorithm: z.ZodOptional<z.ZodOptional<z.ZodEnum<["sha256", "sha1", "sha512"]>>>;
+    signing_secret: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    response_status: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    response_body: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    response_content_type: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+}, "endpoint_id">, "strip", z.ZodTypeAny, {
+    label?: string | undefined;
+    hmac_header?: string | undefined;
+    hmac_algorithm?: "sha256" | "sha1" | "sha512" | undefined;
+    trigger_mode?: "buffer" | "immediate" | undefined;
+    response_status?: number | undefined;
+    response_body?: string | undefined;
+    response_content_type?: string | undefined;
+    signing_secret?: string | undefined;
+}, {
+    label?: string | undefined;
+    hmac_header?: string | undefined;
+    hmac_algorithm?: "sha256" | "sha1" | "sha512" | undefined;
+    trigger_mode?: "buffer" | "immediate" | undefined;
+    response_status?: number | undefined;
+    response_body?: string | undefined;
+    response_content_type?: string | undefined;
+    signing_secret?: string | undefined;
+}>;
+export type WebhookEndpointPatchInput = z.infer<typeof webhookEndpointPatchInputSchema>;
+export declare const webhookEventForSdkSchema: z.ZodObject<{
+    id: z.ZodString;
+    received_at: z.ZodString;
+    method: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodNullable<z.ZodString>;
+    body_base64: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    body: string | null;
+    received_at: string;
+    method: string;
+    headers: Record<string, string>;
+    body_base64: string | null;
+}, {
+    id: string;
+    body: string | null;
+    received_at: string;
+    method: string;
+    headers: Record<string, string>;
+    body_base64: string | null;
+}>;
+export type WebhookEventForSdk = z.infer<typeof webhookEventForSdkSchema>;
+//# sourceMappingURL=webhook-endpoint.schema.d.ts.map

package/dist/schemas/webhook-endpoint.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-endpoint.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/webhook-endpoint.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;GAiBG;AAKH,eAAO,MAAM,uBAAuB,aAOjC,CAAA;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE,eAAO,MAAM,wBAAwB,oCAAkC,CAAA;AACvE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEzE,eAAO,MAAM,0BAA0B,yCAAuC,CAAA;AAC9E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU3C,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAA;AAEzF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAC4B,CAAA;AACxE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAKvF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAOnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}

package/dist/schemas/webhook-endpoint.schema.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+/**
+ * Webhook endpoint declarations — each one mints a stable HTTPS URL on
+ * `in.prave.app/w/<runs.webhook_token>/<endpoint_id>` that buffers
+ * inbound traffic into `webhook_events` (or, when trigger_mode is
+ * 'immediate', also enqueues a fresh run execution).
+ *
+ * Two flavours of inbound traffic share this surface:
+ *   • short-lived OAuth callbacks (`?code=…&state=…`) — almost always
+ *     'immediate' so the code is exchanged before its ~10-minute window
+ *     closes;
+ *   • long-tail webhooks (Slack interactivity, TikTok post.published,
+ *     etc.) — 'buffer', drained by `prave.webhooks.drain()` on the
+ *     next cron run.
+ *
+ * HMAC verification is optional and only meaningful for buffered
+ * webhooks where the provider signs the body. OAuth callbacks rarely
+ * sign — providers rely on the redirect_uri being preregistered.
+ */
+// URL-path-segment shaped — short and lowercase. Skill-builders use
+// it both in their `prave.webhooks.drain('<endpoint_id>')` calls and as
+// the literal path segment in the public URL.
+export const webhookEndpointIdSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/, 'Lowercase letters, digits and dashes — must start and end with an alphanumeric.');
+export const webhookTriggerModeSchema = z.enum(['buffer', 'immediate']);
+export const webhookHmacAlgorithmSchema = z.enum(['sha256', 'sha1', 'sha512']);
+export const webhookEndpointSchema = z.object({
+    id: z.string().uuid(),
+    endpoint_id: webhookEndpointIdSchema,
+    label: z.string().nullable(),
+    // Public URL the user pastes into their provider's developer console.
+    url: z.string().url(),
+    // HMAC config — `null` everywhere means no verification.
+    hmac_header: z.string().max(80).nullable(),
+    hmac_algorithm: webhookHmacAlgorithmSchema.nullable(),
+    // Last 4 chars of the signing secret, to confirm "yes I have one set".
+    signing_secret_preview: z.string().nullable(),
+    trigger_mode: webhookTriggerModeSchema,
+    // Static-response config (Slack slash command wants "200 ok" right back).
+    response_status: z.number().int().min(100).max(599),
+    response_body: z.string().nullable(),
+    response_content_type: z.string().nullable(),
+    // Stats surfaced in the UI card.
+    events_30d: z.number().int().nonnegative().optional(),
+    last_received_at: z.string().datetime().nullable().optional(),
+    created_at: z.string().datetime(),
+    updated_at: z.string().datetime(),
+});
+export const webhookEndpointCreateInputSchema = z.object({
+    endpoint_id: webhookEndpointIdSchema,
+    label: z.string().max(120).optional(),
+    trigger_mode: webhookTriggerModeSchema.default('buffer'),
+    hmac_header: z.string().max(80).optional(),
+    hmac_algorithm: webhookHmacAlgorithmSchema.optional(),
+    signing_secret: z.string().min(8).max(512).optional(),
+    response_status: z.number().int().min(100).max(599).optional(),
+    response_body: z.string().max(8_192).optional(),
+    response_content_type: z.string().max(120).optional(),
+});
+export const webhookEndpointPatchInputSchema = webhookEndpointCreateInputSchema.partial().omit({ endpoint_id: true });
+// Shape returned to the SDK by GET /api/v1/sdk/webhooks/:endpointId.
+// `body` is a UTF-8 best-effort decode; binary uploads return
+// `body_base64` instead. Headers are forwarded as the captured object.
+export const webhookEventForSdkSchema = z.object({
+    id: z.string().uuid(),
+    received_at: z.string().datetime(),
+    method: z.string(),
+    headers: z.record(z.string(), z.string()),
+    body: z.string().nullable(),
+    body_base64: z.string().nullable(),
+});

package/dist/types/plan-limits.d.ts

@@ -145,6 +145,29 @@ export interface PlanLimits {
     runs_max_timeout_seconds: number;
     /** Max stdout/stderr captured per execution (bytes). */
     runs_max_log_bytes: number;
+    /**
+     * Vault keys per run. Each key holds a single user-supplied secret
+     * (API key, OAuth client_secret, etc.) readable from the skill via
+     * `prave.vault.get('KEY')`. `null` = unlimited.
+     */
+    vault_keys_max: number | null;
+    /**
+     * Per-run KV bytes budget — the total encrypted-value size summed
+     * across all `run_kv` rows for the run. Hits 413 on PUT once
+     * exceeded. `null` = unlimited.
+     */
+    kv_bytes_max: number | null;
+    /**
+     * Webhook endpoints per run. Each endpoint mints one stable URL on
+     * `in.prave.app/w/<token>/<endpoint_id>`. `null` = unlimited.
+     */
+    webhooks_max: number | null;
+    /**
+     * Inbound webhook events per day across all endpoints on the run.
+     * Over-cap requests are dropped with 429 (event NOT buffered).
+     * `null` = unlimited.
+     */
+    webhook_events_per_day: number | null;
 }
 export declare const PLAN_LIMITS: Record<Plan, PlanLimits>;
 export declare const PLAN_RANK: Record<Plan, number>;

package/dist/types/plan-limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-limits.d.ts","sourceRoot":"","sources":["../../src/types/plan-limits.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-limits.d.ts","sourceRoot":"","sources":["../../src/types/plan-limits.ts"],"names":[],"mappings":"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"}

package/dist/types/plan-limits.js

@@ -54,6 +54,10 @@ export const PLAN_LIMITS = {
         runs_min_frequency: 'none',
         runs_max_timeout_seconds: 0,
         runs_max_log_bytes: 0,
+        vault_keys_max: 0,
+        kv_bytes_max: 0,
+        webhooks_max: 0,
+        webhook_events_per_day: 0,
     },
     // ── Pro (internally `explorer`) ───────────────────────────────────
     explorer: {
@@ -104,6 +108,10 @@ export const PLAN_LIMITS = {
         runs_min_frequency: 'daily',
         runs_max_timeout_seconds: 60,
         runs_max_log_bytes: 65_536,
+        vault_keys_max: 25,
+        kv_bytes_max: 1_048_576,
+        webhooks_max: 5,
+        webhook_events_per_day: 5_000,
     },
     // ── Max (internally `creator`) ────────────────────────────────────
     creator: {
@@ -152,6 +160,10 @@ export const PLAN_LIMITS = {
         runs_min_frequency: 'custom',
         runs_max_timeout_seconds: 300,
         runs_max_log_bytes: 262_144,
+        vault_keys_max: null,
+        kv_bytes_max: 16_777_216,
+        webhooks_max: null,
+        webhook_events_per_day: 50_000,
     },
 };
 export const PLAN_RANK = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/shared",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "type": "module",
   "publishConfig": {
     "access": "public"