@trigora/sdk 0.4.0 → 0.6.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
@@ -139,7 +142,7 @@ import { defineFlow } from '@trigora/sdk';
 
 export default defineFlow({
   id: 'status',
-  trigger: { type: 'webhook' },
+  trigger: { type: 'webhook', route: '/status' },
   async run() {
     return {
       ok: true,
@@ -189,10 +192,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 +217,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,14 +1,24 @@
-import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDefinition } from '@trigora/contracts';
+import type { CronEventPayload, CronFlowDefinition, FlowDefinition, FlowRunFn, JsonValue, ManualFlowDefinition, ManualTrigger, 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;
+};
+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>;
 /**
  * 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
@@ -20,8 +30,8 @@ import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDe
  * @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 };
@@ -29,6 +39,8 @@ import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDe
  * });
  * ```
  */
+export declare function defineFlow<TTrigger extends Trigger, TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: DefineFlowInput<TPayload, TEnv, TTrigger>): DefineFlowOutput<TPayload, TEnv, TTrigger>;
 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<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: CronFlowDefinition<TPayload, TEnv>): CronFlowDefinition<TPayload, TEnv>;
+export declare function defineFlow<TEnv extends Record<string, string> = Record<string, string>>(flow: CronFlowDefinition<TEnv>): CronFlowDefinition<TEnv>;
+export {};

package/dist/github.d.ts

@@ -1,8 +1,8 @@
-import type { FlowEvent } from '@trigora/contracts';
+import type { WebhookFlowEvent } from '@trigora/contracts';
 export type VerifyGitHubWebhookOptions = {
     secret: string | undefined;
 };
 export declare class GitHubWebhookVerificationError extends Error {
     name: string;
 }
-export declare function verifyGitHubWebhook<T = unknown>(event: FlowEvent, options: VerifyGitHubWebhookOptions): Promise<T>;
+export declare function verifyGitHubWebhook<T = unknown>(event: WebhookFlowEvent, options: VerifyGitHubWebhookOptions): Promise<T>;

package/dist/index.d.ts

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

package/dist/stripe.d.ts

@@ -1,4 +1,4 @@
-import type { FlowEvent } from '@trigora/contracts';
+import type { WebhookFlowEvent } from '@trigora/contracts';
 export type VerifyStripeWebhookOptions = {
     secret: string | undefined;
     toleranceSeconds?: number;
@@ -6,4 +6,4 @@ export type VerifyStripeWebhookOptions = {
 export declare class StripeWebhookVerificationError extends Error {
     name: string;
 }
-export declare function verifyStripeWebhook<T = unknown>(event: FlowEvent, options: VerifyStripeWebhookOptions): Promise<T>;
+export declare function verifyStripeWebhook<T = unknown>(event: WebhookFlowEvent, options: VerifyStripeWebhookOptions): Promise<T>;

package/dist/webhookSignature.d.ts

@@ -1,4 +1,4 @@
-import type { FlowEvent } from '@trigora/contracts';
+import type { WebhookFlowEvent } from '@trigora/contracts';
 export declare function encodeUtf8(value: string): Uint8Array;
 export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;
 export declare function bytesToHex(bytes: Uint8Array): string;
@@ -6,7 +6,7 @@ export declare function getHeaderCaseInsensitive(headers: Record<string, string>
 export declare function isHexString(value: string): boolean;
 export declare function timingSafeEqualStrings(left: string, right: string): boolean;
 export declare function computeHmacSha256Hex(secret: string, signedPayload: string): Promise<string>;
-export declare function requireWebhookRequestParts(event: FlowEvent, providerName: string): {
+export declare function requireWebhookRequestParts(event: WebhookFlowEvent, providerName: string): {
     headers: Record<string, string>;
     rawBody: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/trigora-dev/trigora"
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trigora/contracts": "0.4.1"
+    "@trigora/contracts": "0.6.5"
   },
   "devDependencies": {
     "tsup": "^8.5.1"