@trigora/sdk 0.1.3 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @trigora/sdk
 
-Define flows for Trigora.
+Flow authoring for Trigora.
 
----
+`@trigora/sdk` is the package most Trigora users write against directly. It provides `defineFlow` plus the shared runtime types needed to author flows with good TypeScript ergonomics.
 
 ## Install
 
@@ -10,7 +10,11 @@ Define flows for Trigora.
 npm install @trigora/sdk
 ```
 
----
+Most projects will install the CLI alongside it:
+
+```bash
+npm install trigora @trigora/sdk
+```
 
 ## Basic Usage
 
@@ -21,51 +25,208 @@ export default defineFlow({
   id: 'hello',
   trigger: { type: 'manual' },
   async run(event, ctx) {
-    await ctx.log.info('Hello');
+    await ctx.log.info('Hello from Trigora', event.payload);
+  },
+});
+```
+
+## What `defineFlow` Gives You
+
+`defineFlow` helps with:
+
+- typed flow definitions
+- typed trigger variants
+- typed event payload access
+- typed runtime context
+- trigger-aware return types
+- compile-time validation of trigger shape
+
+The trigger typing is strict. If you mix properties from different trigger kinds, TypeScript will flag it.
+
+For example, this is invalid:
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'broken',
+  trigger: {
+    type: 'webhook',
+    cron: '* * * * *',
+  },
+  async run() {
+    return 'nope';
   },
 });
 ```
 
----
+## Trigger Types
+
+### Manual
 
-## Flow Structure
+Use manual triggers for local invocation and testing.
 
 ```ts
-defineFlow({
-  id: string,
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'hello',
   trigger: { type: 'manual' },
-  run: async (event, ctx) => {}
-})
+  async run(event, ctx) {
+    await ctx.log.info('Triggered manually', event.payload);
+  },
+});
+```
+
+### Webhook
+
+Use webhook triggers for hosted HTTP entrypoints.
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'ping',
+  trigger: { type: 'webhook' },
+  async run() {
+    return 'pong';
+  },
+});
+```
+
+You can also include an optional event name:
+
+```ts
+trigger: { type: 'webhook', event: 'orders.created' }
+```
+
+### Cron
+
+Use cron triggers for scheduled work.
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'nightly-sync',
+  trigger: { type: 'cron', cron: '0 2 * * *' },
+  async run(event, ctx) {
+    await ctx.log.info('Nightly sync started', event.payload);
+  },
+});
+```
+
+## Return Types
+
+Return values are trigger-aware.
+
+### Webhook flows
+
+Webhook flows can return HTTP-friendly values directly from `run`.
+
+Supported return values:
+
+- `Response`
+- plain objects, arrays, numbers, and booleans
+- `string`
+- `null`
+- `undefined`
+
+Example:
+
+```ts
+import { defineFlow } from '@trigora/sdk';
+
+export default defineFlow({
+  id: 'status',
+  trigger: { type: 'webhook' },
+  async run() {
+    return {
+      ok: true,
+      service: 'trigora',
+    };
+  },
+});
 ```
 
----
+### Manual and cron flows
 
-## Event
+Manual and cron 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
+- webhook flows are request-response flows
+
+## Event Shape
+
+Flows receive an event object:
 
 ```ts
-{
+type FlowEvent<TPayload = JsonValue> = {
   id: string;
   type: string;
   timestamp: string;
-  payload: unknown;
-}
+  payload: TPayload;
+  request?: {
+    headers: Record<string, string>;
+    method: string;
+    url: string;
+    rawBody: string;
+  };
+};
 ```
 
----
+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.
 
 ## Context
 
+Flows receive a context object with logging and environment access:
+
 ```ts
-ctx.log.info()
-ctx.log.warn()
-ctx.log.error()
+ctx.log.info('message')
+ctx.log.warn('message')
+ctx.log.error('message')
 
 ctx.env
 ```
 
----
+The exact exported type is `FlowContext<TEnv>`.
+
+## Exported Types
+
+`@trigora/sdk` re-exports the main flow authoring types from `@trigora/contracts`:
+
+- `FlowContext`
+- `FlowDefinition`
+- `FlowEvent`
+- `FlowRunFn`
+- `JsonValue`
+- `Trigger`
+- `WebhookFlowResult`
+
+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 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`
+
+## Related Packages
+
+- `trigora` - CLI for local development and hosted deploys
+- `@trigora/contracts` - shared public types used by the SDK, CLI, and API consumers
 
-## Notes
+## License
 
-- flows are plain TypeScript modules
-- no framework required
+MIT

package/dist/defineFlow.d.ts

@@ -1,2 +1,34 @@
-import type { FlowDefinition } from '@trigora/contracts';
-export declare function defineFlow<TPayload = unknown, TEnv extends Record<string, string> = Record<string, string>>(flow: FlowDefinition<TPayload, TEnv>): FlowDefinition<TPayload, TEnv>;
+import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDefinition } from '@trigora/contracts';
+/**
+ * Define a Trigora flow.
+ *
+ * Flows are plain TypeScript modules with three core parts:
+ * - `id`: the source 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.
+ *
+ * Webhook flows can return HTTP-friendly values:
+ * - `Response`
+ * - plain objects / arrays / numbers / booleans
+ * - `string`
+ * - `null` or `undefined`
+ *
+ * Other trigger types generally do not need to return anything meaningful.
+ *
+ * @example
+ * ```ts
+ * export default defineFlow({
+ *   id: 'hello',
+ *   trigger: { type: 'webhook' },
+ *   async run(event, ctx) {
+ *     await ctx.log.info('Received event', event.payload);
+ *     return { ok: true };
+ *   },
+ * });
+ * ```
+ */
+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/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/trigora-dev/trigora"
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trigora/contracts": "0.1.0"
+    "@trigora/contracts": "0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"