@trigora/sdk 0.1.3 → 0.2.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,201 @@ export default defineFlow({
   id: 'hello',
   trigger: { type: 'manual' },
   async run(event, ctx) {
-    await ctx.log.info('Hello');
+    await ctx.log.info('Hello from Trigora', {
+      payload: 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', {
+      payload: 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
 
-## Event
+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', {
+      payload: 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
+
+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 = unknown> = {
   id: string;
   type: string;
   timestamp: string;
-  payload: unknown;
-}
+  payload: TPayload;
+};
 ```
 
----
+In local CLI runs, the payload comes from your JSON payload file when one is provided.
 
 ## 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` or `trigora dev`
+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,32 @@
-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 { FlowDefinition, Trigger } 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', { payload: 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>;

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.2.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.2.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"