@trigora/sdk 0.5.0 → 0.8.0

package/README.md

@@ -86,18 +86,21 @@ Use webhook triggers for hosted HTTP entrypoints.
 import { defineFlow } from '@trigora/sdk';
 
 export default defineFlow({
-  id: 'ping',
-  trigger: { type: 'webhook' },
+  id: 'stripe-webhook',
+  trigger: { type: 'webhook', route: '/hooks/stripe' },
   async run() {
     return 'pong';
   },
 });
 ```
 
+`id` is the internal flow identifier used by the CLI. `route` is the optional public hosted webhook path.
+When `route` is omitted, hosted ingress defaults to `/${id}`.
+
 You can also include an optional event name:
 
 ```ts
-trigger: { type: 'webhook', event: 'orders.created' }
+trigger: { type: 'webhook', event: 'orders.created', route: '/hooks/orders' }
 ```
 
 ### Cron
@@ -116,6 +119,28 @@ export default defineFlow({
 });
 ```
 
+### Queue
+
+Use queue triggers to consume workspace-scoped queue messages. Deploy auto-provisions and binds the named queue to the flow.
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'process-image',
+  trigger: { type: 'queue', queue: 'image-processing' },
+  async run(event, ctx) {
+    await ctx.log.info('Processing message', {
+      queue: event.queue,
+      messageId: event.messageId,
+      payload: event.payload,
+    });
+  },
+});
+```
+
+Locally, `trigora trigger` and `trigora dev` invoke queue flows with a synthetic `QueueFlowEvent` (`messageId` starts with `local_`). Hosted runs use the real message id.
+
 ## Return Types
 
 Return values are trigger-aware.
@@ -139,7 +164,7 @@ import { defineFlow } from '@trigora/sdk';
 
 export default defineFlow({
   id: 'status',
-  trigger: { type: 'webhook' },
+  trigger: { type: 'webhook', route: '/status' },
   async run() {
     return {
       ok: true,
@@ -149,14 +174,15 @@ export default defineFlow({
 });
 ```
 
-### Manual and cron flows
+### Manual, cron, and queue flows
 
-Manual and cron flows do not use return values. Their `run` functions are typed as `void`.
+Manual, cron, and queue flows do not use return values. Their `run` functions are typed as `void`.
 
 This matches how Trigora uses them:
 
 - manual flows are invoked locally for testing and development
 - cron flows are background-style scheduled jobs
+- queue flows consume workspace queue messages
 - webhook flows are request-response flows
 
 ## Event Shape
@@ -189,10 +215,19 @@ For webhook flows, request metadata may also be available on `event.request`, in
 Trigora includes a small helper for verifying Stripe webhook signatures:
 
 ```ts
+import { defineFlow } from '@trigora/sdk';
 import { verifyStripeWebhook } from '@trigora/sdk/stripe';
 
-const stripeEvent = await verifyStripeWebhook(event, {
-  secret: ctx.env.STRIPE_WEBHOOK_SECRET,
+export default defineFlow({
+  id: 'stripe-webhook',
+  trigger: { type: 'webhook', route: '/hooks/stripe' },
+  async run(event, ctx) {
+    await verifyStripeWebhook(event, {
+      secret: ctx.env.STRIPE_WEBHOOK_SECRET,
+    });
+
+    return { ok: true };
+  },
 });
 ```
 
@@ -205,10 +240,19 @@ Production Stripe webhooks should verify signatures before trusting payloads.
 Trigora includes a small helper for verifying GitHub webhook signatures:
 
 ```ts
+import { defineFlow } from '@trigora/sdk';
 import { verifyGitHubWebhook } from '@trigora/sdk/github';
 
-const githubEvent = await verifyGitHubWebhook(event, {
-  secret: ctx.env.GITHUB_WEBHOOK_SECRET,
+export default defineFlow({
+  id: 'github-webhook',
+  trigger: { type: 'webhook', route: '/hooks/github' },
+  async run(event, ctx) {
+    await verifyGitHubWebhook(event, {
+      secret: ctx.env.GITHUB_WEBHOOK_SECRET,
+    });
+
+    return { ok: true };
+  },
 });
 ```
 

package/dist/defineFlow.d.ts

@@ -1,20 +1,24 @@
-import type { CronEventPayload, CronFlowDefinition, FlowDefinition, FlowRunFn, JsonValue, ManualFlowDefinition, ManualTrigger, Trigger, WebhookTrigger, WebhookFlowDefinition, CronTrigger } from '@trigora/contracts';
+import type { CronEventPayload, CronFlowDefinition, FlowDefinition, FlowRunFn, JsonValue, ManualFlowDefinition, ManualTrigger, QueueFlowDefinition, QueueTrigger, Trigger, WebhookTrigger, WebhookFlowDefinition, CronTrigger } from '@trigora/contracts';
 type DefineFlowInput<TPayload, TEnv extends Record<string, string>, TTrigger extends Trigger> = {
     id: string;
     trigger: TTrigger;
-    run: TTrigger extends ManualTrigger ? FlowRunFn<TPayload, TEnv, ManualTrigger> : TTrigger extends WebhookTrigger ? FlowRunFn<TPayload, TEnv, WebhookTrigger> : TTrigger extends CronTrigger ? FlowRunFn<CronEventPayload, TEnv, CronTrigger> : never;
+    run: TTrigger extends ManualTrigger ? FlowRunFn<TPayload, TEnv, ManualTrigger> : TTrigger extends WebhookTrigger ? FlowRunFn<TPayload, TEnv, WebhookTrigger> : TTrigger extends CronTrigger ? FlowRunFn<CronEventPayload, TEnv, CronTrigger> : TTrigger extends QueueTrigger ? FlowRunFn<TPayload, TEnv, QueueTrigger> : never;
 };
-type DefineFlowOutput<TPayload, TEnv extends Record<string, string>, TTrigger extends Trigger> = TTrigger extends ManualTrigger ? ManualFlowDefinition<TPayload, TEnv> : TTrigger extends WebhookTrigger ? WebhookFlowDefinition<TPayload, TEnv> : TTrigger extends CronTrigger ? CronFlowDefinition<TEnv> : FlowDefinition<TPayload, TEnv, TTrigger>;
+type DefineFlowOutput<TPayload, TEnv extends Record<string, string>, TTrigger extends Trigger> = TTrigger extends ManualTrigger ? ManualFlowDefinition<TPayload, TEnv> : TTrigger extends WebhookTrigger ? WebhookFlowDefinition<TPayload, TEnv> : TTrigger extends CronTrigger ? CronFlowDefinition<TEnv> : TTrigger extends QueueTrigger ? QueueFlowDefinition<TPayload, TEnv> : FlowDefinition<TPayload, TEnv, TTrigger>;
 /**
  * Define a Trigora flow.
  *
  * Flows are plain TypeScript modules with three core parts:
- * - `id`: the source identifier for the flow in your project
+ * - `id`: the internal identifier for the flow in your project
  * - `trigger`: how the flow is invoked
  * - `run`: the function that executes when the flow is triggered
  *
  * `run` receives the incoming `event` and a `ctx` object with logging and environment access.
  *
+ * For webhook flows, `trigger.route` controls the public hosted path and defaults to `/${id}`.
+ * This is separate from the flow `id`, which is still what the CLI uses for commands like
+ * `trigora deploy hello` or `trigora flows inspect hello`.
+ *
  * Webhook flows can return HTTP-friendly values:
  * - `Response`
  * - plain objects / arrays / numbers / booleans
@@ -26,8 +30,8 @@ type DefineFlowOutput<TPayload, TEnv extends Record<string, string>, TTrigger ex
  * @example
  * ```ts
  * export default defineFlow({
- *   id: 'hello',
- *   trigger: { type: 'webhook' },
+ *   id: 'stripe-webhook',
+ *   trigger: { type: 'webhook', route: '/hooks/stripe' },
  *   async run(event, ctx) {
  *     await ctx.log.info('Received event', event.payload);
  *     return { ok: true };
@@ -39,4 +43,5 @@ export declare function defineFlow<TTrigger extends Trigger, TPayload = JsonValu
 export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: ManualFlowDefinition<TPayload, TEnv>): ManualFlowDefinition<TPayload, TEnv>;
 export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: WebhookFlowDefinition<TPayload, TEnv>): WebhookFlowDefinition<TPayload, TEnv>;
 export declare function defineFlow<TEnv extends Record<string, string> = Record<string, string>>(flow: CronFlowDefinition<TEnv>): CronFlowDefinition<TEnv>;
+export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: QueueFlowDefinition<TPayload, TEnv>): QueueFlowDefinition<TPayload, TEnv>;
 export {};

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { defineFlow } from './defineFlow';
-export type { CronEventPayload, CronFlowEvent, FlowContext, FlowDefinition, FlowEvent, FlowRunFn, JsonValue, ManualFlowEvent, Trigger, WebhookFlowEvent, WebhookFlowResult, } from '@trigora/contracts';
+export type { CronEventPayload, CronFlowEvent, FlowContext, FlowDefinition, FlowEvent, FlowRunFn, JsonValue, ManualFlowEvent, QueueFlowEvent, Trigger, WebhookFlowEvent, WebhookFlowResult, } from '@trigora/contracts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/trigora-dev/trigora"
@@ -18,6 +18,7 @@
     "cli",
     "triggers",
     "cron",
+    "queues",
     "webhooks"
   ],
   "license": "MIT",
@@ -45,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trigora/contracts": "0.5.5"
+    "@trigora/contracts": "0.8.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1"