@trigora/sdk 0.6.0 → 0.9.0

package/README.md

@@ -119,6 +119,33 @@ export default defineFlow({
 });
 ```
 
+### Queue
+
+Use queue triggers to consume workspace-scoped queue messages. Deploy auto-provisions and binds the named queue to the flow.
+
+Optional `retry` configures how many times a failed message may be redelivered. Omitted `retry` means a single attempt. `attempts > 1` is supported for queue flows only.
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'process-image',
+  trigger: { type: 'queue', queue: 'image-processing' },
+  retry: { attempts: 5, backoff: 'exponential' },
+  async run(event, ctx) {
+    await ctx.log.info('Processing message', {
+      queue: event.queue,
+      messageId: event.messageId,
+      attempt: event.attempt,
+      maxAttempts: event.maxAttempts,
+      payload: event.payload,
+    });
+  },
+});
+```
+
+Locally, `trigora trigger` and `trigora dev` invoke queue flows with a synthetic `QueueFlowEvent` (`messageId` starts with `local_`, `attempt` is `1`, and `maxAttempts` comes from `retry.attempts` or `1`). Local runs do not actually retry. Hosted runs use the real message id and attempt count.
+
 ## Return Types
 
 Return values are trigger-aware.
@@ -152,14 +179,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
@@ -181,6 +209,15 @@ type FlowEvent<TPayload = JsonValue> = {
 };
 ```
 
+Queue events also include:
+
+```ts
+queue: string;
+messageId: string;
+attempt: number;      // 1-based delivery count
+maxAttempts: number;  // from retry.attempts, or 1 when omitted
+```
+
 In local manual runs, the payload comes from your JSON payload file when one is provided. In local webhook dev and deployed webhook flows, the payload is the parsed JSON request body.
 
 If you do not provide your own payload type, `event.payload` defaults to `JsonValue`.
@@ -260,6 +297,7 @@ The exact exported type is `FlowContext<TEnv>`.
 - `FlowEvent`
 - `FlowRunFn`
 - `JsonValue`
+- `RetryPolicy`
 - `Trigger`
 - `WebhookFlowResult`
 

package/dist/defineFlow.d.ts

@@ -1,10 +1,15 @@
-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, RetryPolicy, 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;
+    /**
+     * Optional retry policy. Omitted means a single attempt.
+     * `attempts > 1` is supported for queue flows only (enforced at deploy time).
+     */
+    retry?: RetryPolicy;
+    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.
  *
@@ -12,6 +17,7 @@ type DefineFlowOutput<TPayload, TEnv extends Record<string, string>, TTrigger ex
  * - `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
+ * - `retry`: optional retry policy (queue flows may use `attempts > 1`)
  *
  * `run` receives the incoming `event` and a `ctx` object with logging and environment access.
  *
@@ -43,4 +49,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, RetryBackoff, RetryPolicy, Trigger, WebhookFlowEvent, WebhookFlowResult, } from '@trigora/contracts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.6.0",
+  "version": "0.9.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.6.5"
+    "@trigora/contracts": "^0.9.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"