@trigora/sdk 0.2.0 → 0.4.0

package/README.md

@@ -25,9 +25,7 @@ export default defineFlow({
   id: 'hello',
   trigger: { type: 'manual' },
   async run(event, ctx) {
-    await ctx.log.info('Hello from Trigora', {
-      payload: event.payload,
-    });
+    await ctx.log.info('Hello from Trigora', event.payload);
   },
 });
 ```
@@ -75,9 +73,7 @@ export default defineFlow({
   id: 'hello',
   trigger: { type: 'manual' },
   async run(event, ctx) {
-    await ctx.log.info('Triggered manually', {
-      payload: event.payload,
-    });
+    await ctx.log.info('Triggered manually', event.payload);
   },
 });
 ```
@@ -115,9 +111,7 @@ export default defineFlow({
   id: 'nightly-sync',
   trigger: { type: 'cron', cron: '0 2 * * *' },
   async run(event, ctx) {
-    await ctx.log.info('Nightly sync started', {
-      payload: event.payload,
-    });
+    await ctx.log.info('Nightly sync started', event.payload);
   },
 });
 ```
@@ -170,15 +164,55 @@ This matches how Trigora uses them:
 Flows receive an event object:
 
 ```ts
-type FlowEvent<TPayload = unknown> = {
+type FlowEvent<TPayload = JsonValue> = {
   id: string;
   type: string;
   timestamp: string;
   payload: TPayload;
+  request?: {
+    headers: Record<string, string>;
+    method: string;
+    url: string;
+    rawBody: string;
+  };
 };
 ```
 
-In local CLI runs, the payload comes from your JSON payload file when one is provided.
+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`.
+
+For webhook flows, request metadata may also be available on `event.request`, including headers, method, URL, and the raw request body. `event.request.rawBody` is useful when you want to verify webhook signatures yourself.
+
+## Stripe Webhooks
+
+Trigora includes a small helper for verifying Stripe webhook signatures:
+
+```ts
+import { verifyStripeWebhook } from '@trigora/sdk/stripe';
+
+const stripeEvent = await verifyStripeWebhook(event, {
+  secret: ctx.env.STRIPE_WEBHOOK_SECRET,
+});
+```
+
+This verifies against `event.request.rawBody` and the `Stripe-Signature` header.
+
+Production Stripe webhooks should verify signatures before trusting payloads.
+
+## GitHub Webhooks
+
+Trigora includes a small helper for verifying GitHub webhook signatures:
+
+```ts
+import { verifyGitHubWebhook } from '@trigora/sdk/github';
+
+const githubEvent = await verifyGitHubWebhook(event, {
+  secret: ctx.env.GITHUB_WEBHOOK_SECRET,
+});
+```
+
+This verifies against `event.request.rawBody` and the `X-Hub-Signature-256` header.
 
 ## Context
 
@@ -192,6 +226,8 @@ ctx.log.error('message')
 ctx.env
 ```
 
+In local CLI runs, `ctx.env` includes the process environment after loading `.env` and `.env.local`, with existing shell variables taking precedence.
+
 The exact exported type is `FlowContext<TEnv>`.
 
 ## Exported Types
@@ -211,7 +247,10 @@ That means most flow authors can stay entirely within `@trigora/sdk`.
 ## Typical Workflow
 
 1. Define a flow with `defineFlow`
-2. Run it locally with `trigora trigger` or `trigora dev`
+2. Run it locally with:
+   - `trigora trigger hello --payload payload.json` for one-off runs
+   - `trigora dev hello --payload payload.json` for manual or payload watch mode
+   - `trigora dev stripe-checkout` for a local webhook server
 3. Deploy webhook flows with `trigora deploy`
 4. Manage hosted flows with `trigora flows`
 

package/dist/defineFlow.d.ts

@@ -1,4 +1,4 @@
-import type { FlowDefinition, Trigger } from '@trigora/contracts';
+import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDefinition } from '@trigora/contracts';
 /**
  * Define a Trigora flow.
  *
@@ -23,10 +23,12 @@ import type { FlowDefinition, Trigger } from '@trigora/contracts';
  *   id: 'hello',
  *   trigger: { type: 'webhook' },
  *   async run(event, ctx) {
- *     await ctx.log.info('Received event', { payload: event.payload });
+ *     await ctx.log.info('Received event', event.payload);
  *     return { ok: true };
  *   },
  * });
  * ```
  */
-export declare function defineFlow<TPayload = unknown, TEnv extends Record<string, string> = Record<string, string>, TTrigger extends Trigger = Trigger>(flow: FlowDefinition<TPayload, TEnv, TTrigger>): FlowDefinition<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>;

package/dist/github.d.ts

@@ -0,0 +1,8 @@
+import type { FlowEvent } 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>;

package/dist/github.js

@@ -0,0 +1,120 @@
+// src/webhookSignature.ts
+function encodeUtf8(value) {
+  return new TextEncoder().encode(value);
+}
+function toArrayBuffer(bytes) {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+  const normalizedName = headerName.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isHexString(value) {
+  return value.length > 0 && value.length % 2 === 0 && /^[0-9a-f]+$/i.test(value);
+}
+function timingSafeEqualStrings(left, right) {
+  const leftBytes = encodeUtf8(left);
+  const rightBytes = encodeUtf8(right);
+  const length = Math.max(leftBytes.length, rightBytes.length);
+  let difference = leftBytes.length === rightBytes.length ? 0 : 1;
+  for (let index = 0; index < length; index += 1) {
+    difference |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+  }
+  return difference === 0;
+}
+async function computeHmacSha256Hex(secret, signedPayload) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("Web Crypto API is unavailable in this runtime.");
+  }
+  const key = await subtle.importKey(
+    "raw",
+    toArrayBuffer(encodeUtf8(secret)),
+    {
+      name: "HMAC",
+      hash: "SHA-256"
+    },
+    false,
+    ["sign"]
+  );
+  const signature = await subtle.sign("HMAC", key, toArrayBuffer(encodeUtf8(signedPayload)));
+  return bytesToHex(new Uint8Array(signature));
+}
+function requireWebhookRequestParts(event, providerName) {
+  if (!event.request || typeof event.request.headers !== "object" || event.request.headers === null) {
+    throw new Error(`${providerName} webhook request metadata is required.`);
+  }
+  if (typeof event.request.rawBody !== "string") {
+    throw new Error(`${providerName} webhook raw body is required.`);
+  }
+  return {
+    headers: event.request.headers,
+    rawBody: event.request.rawBody
+  };
+}
+
+// src/github.ts
+var GITHUB_SIGNATURE_HEADER = "x-hub-signature-256";
+var GITHUB_SIGNATURE_PREFIX = "sha256=";
+var GitHubWebhookVerificationError = class extends Error {
+  name = "GitHubWebhookVerificationError";
+};
+function createVerificationError(message) {
+  return new GitHubWebhookVerificationError(message);
+}
+function parseGitHubSignatureHeader(headerValue) {
+  const normalizedValue = headerValue.trim();
+  if (!normalizedValue.toLowerCase().startsWith(GITHUB_SIGNATURE_PREFIX)) {
+    return null;
+  }
+  const signature = normalizedValue.slice(GITHUB_SIGNATURE_PREFIX.length).trim().toLowerCase();
+  if (!isHexString(signature)) {
+    return null;
+  }
+  return signature;
+}
+async function verifyGitHubWebhook(event, options) {
+  if (!options.secret || options.secret.trim().length === 0) {
+    throw createVerificationError("A GitHub webhook secret is required.");
+  }
+  let requestParts;
+  try {
+    requestParts = requireWebhookRequestParts(event, "GitHub");
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const signatureHeader = getHeaderCaseInsensitive(requestParts.headers, GITHUB_SIGNATURE_HEADER);
+  if (!signatureHeader) {
+    throw createVerificationError("X-Hub-Signature-256 header is required.");
+  }
+  const parsedSignature = parseGitHubSignatureHeader(signatureHeader);
+  if (!parsedSignature) {
+    throw createVerificationError("X-Hub-Signature-256 header is invalid.");
+  }
+  let expectedSignature;
+  try {
+    expectedSignature = await computeHmacSha256Hex(options.secret, requestParts.rawBody);
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  if (!timingSafeEqualStrings(parsedSignature, expectedSignature)) {
+    throw createVerificationError("GitHub webhook signature did not match.");
+  }
+  try {
+    return JSON.parse(requestParts.rawBody);
+  } catch {
+    throw createVerificationError("GitHub webhook body contained invalid JSON.");
+  }
+}
+export {
+  GitHubWebhookVerificationError,
+  verifyGitHubWebhook
+};

package/dist/stripe.d.ts

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

package/dist/stripe.js

@@ -0,0 +1,147 @@
+// src/webhookSignature.ts
+function encodeUtf8(value) {
+  return new TextEncoder().encode(value);
+}
+function toArrayBuffer(bytes) {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+  const normalizedName = headerName.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isHexString(value) {
+  return value.length > 0 && value.length % 2 === 0 && /^[0-9a-f]+$/i.test(value);
+}
+function timingSafeEqualStrings(left, right) {
+  const leftBytes = encodeUtf8(left);
+  const rightBytes = encodeUtf8(right);
+  const length = Math.max(leftBytes.length, rightBytes.length);
+  let difference = leftBytes.length === rightBytes.length ? 0 : 1;
+  for (let index = 0; index < length; index += 1) {
+    difference |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+  }
+  return difference === 0;
+}
+async function computeHmacSha256Hex(secret, signedPayload) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("Web Crypto API is unavailable in this runtime.");
+  }
+  const key = await subtle.importKey(
+    "raw",
+    toArrayBuffer(encodeUtf8(secret)),
+    {
+      name: "HMAC",
+      hash: "SHA-256"
+    },
+    false,
+    ["sign"]
+  );
+  const signature = await subtle.sign("HMAC", key, toArrayBuffer(encodeUtf8(signedPayload)));
+  return bytesToHex(new Uint8Array(signature));
+}
+function requireWebhookRequestParts(event, providerName) {
+  if (!event.request || typeof event.request.headers !== "object" || event.request.headers === null) {
+    throw new Error(`${providerName} webhook request metadata is required.`);
+  }
+  if (typeof event.request.rawBody !== "string") {
+    throw new Error(`${providerName} webhook raw body is required.`);
+  }
+  return {
+    headers: event.request.headers,
+    rawBody: event.request.rawBody
+  };
+}
+
+// src/stripe.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var STRIPE_SIGNATURE_HEADER = "stripe-signature";
+var StripeWebhookVerificationError = class extends Error {
+  name = "StripeWebhookVerificationError";
+};
+function createVerificationError(message) {
+  return new StripeWebhookVerificationError(message);
+}
+function parseStripeSignatureHeader(headerValue) {
+  let timestamp;
+  const signatures = [];
+  for (const part of headerValue.split(",")) {
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+    const key = part.slice(0, separatorIndex).trim();
+    const value = part.slice(separatorIndex + 1).trim();
+    if (key === "t") {
+      const parsedTimestamp = Number(value);
+      if (!Number.isInteger(parsedTimestamp)) {
+        return null;
+      }
+      timestamp = parsedTimestamp;
+      continue;
+    }
+    if (key === "v1" && isHexString(value)) {
+      signatures.push(value.toLowerCase());
+    }
+  }
+  if (timestamp === void 0 || signatures.length === 0) {
+    return null;
+  }
+  return { timestamp, signatures };
+}
+async function verifyStripeWebhook(event, options) {
+  if (!options.secret || options.secret.trim().length === 0) {
+    throw createVerificationError("A Stripe webhook secret is required.");
+  }
+  let requestParts;
+  try {
+    requestParts = requireWebhookRequestParts(event, "Stripe");
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const signatureHeader = getHeaderCaseInsensitive(requestParts.headers, STRIPE_SIGNATURE_HEADER);
+  if (!signatureHeader) {
+    throw createVerificationError("Stripe-Signature header is required.");
+  }
+  const parsedHeader = parseStripeSignatureHeader(signatureHeader);
+  if (!parsedHeader) {
+    throw createVerificationError("Stripe-Signature header is invalid.");
+  }
+  const toleranceSeconds = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (toleranceSeconds !== 0) {
+    const currentTimestamp = Math.floor(Date.now() / 1e3);
+    if (Math.abs(currentTimestamp - parsedHeader.timestamp) > toleranceSeconds) {
+      throw createVerificationError("Stripe webhook timestamp is outside the allowed tolerance.");
+    }
+  }
+  const signedPayload = `${parsedHeader.timestamp}.${requestParts.rawBody}`;
+  let expectedSignature;
+  try {
+    expectedSignature = await computeHmacSha256Hex(options.secret, signedPayload);
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const matches = parsedHeader.signatures.some(
+    (signature) => timingSafeEqualStrings(signature, expectedSignature)
+  );
+  if (!matches) {
+    throw createVerificationError("Stripe webhook signature did not match.");
+  }
+  try {
+    return JSON.parse(requestParts.rawBody);
+  } catch {
+    throw createVerificationError("Stripe webhook body contained invalid JSON.");
+  }
+}
+export {
+  StripeWebhookVerificationError,
+  verifyStripeWebhook
+};

package/dist/webhookSignature.d.ts

@@ -0,0 +1,12 @@
+import type { FlowEvent } from '@trigora/contracts';
+export declare function encodeUtf8(value: string): Uint8Array;
+export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function getHeaderCaseInsensitive(headers: Record<string, string>, headerName: string): string | undefined;
+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): {
+    headers: Record<string, string>;
+    rawBody: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/trigora-dev/trigora"
@@ -28,6 +28,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./github": {
+      "types": "./dist/github.d.ts",
+      "default": "./dist/github.js"
+    },
+    "./stripe": {
+      "types": "./dist/stripe.d.ts",
+      "default": "./dist/stripe.js"
     }
   },
   "files": [
@@ -37,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trigora/contracts": "0.2.0"
+    "@trigora/contracts": "0.4.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1"