@trayai/helix-sdk 0.92.0 → 0.93.0

package/CHANGELOG.md

@@ -9,6 +9,18 @@ general availability, minor versions may include breaking changes.
 The SDK and [`@trayai/helix-cli`](https://www.npmjs.com/package/@trayai/helix-cli) are
 released together and share a version — install matching versions.
 
+## 0.93.0
+
+### Added
+
+- **Scheduled (cron) functions.** Files under `functions/_scheduled/` can default-export
+  `defineSchedule({ cron, timezone?, handler })` to run on a schedule instead of an HTTP
+  route. `cron` is a 5-field standard expression; `timezone` is an IANA name (default UTC).
+  The handler receives a `ScheduleContext` — the core `ctx` surface plus `ctx.trigger`
+  (`scheduledAt`, `firedAt`, `isManual`) and none of the request-derived fields. Schedules
+  fire on the deployed platform; `helix deploy` registers them. `ScheduleContext` and
+  `ScheduleTrigger` are exported. See the README's "Scheduled functions" section.
+
 ## 0.92.0
 
 ### Changed

package/README.md

@@ -12,6 +12,7 @@ The runtime SDK for **Helix** — a TypeScript-first platform for building integ
 - [The `ctx` object](#the-ctx-object)
 - [Authenticated HTTP](#authenticated-http)
 - [Capability modules](#capability-modules)
+- [Scheduled functions](#scheduled-functions)
 - [Authentication](#authentication)
 - [Configuration](#configuration)
 - [Logging](#logging)
@@ -68,7 +69,7 @@ export default defineFunction(async (ctx) => {
 
 ## The `ctx` object
 
-Every handler receives a `ctx` (`TrayContext`). You can also reach the current context anywhere in the async call tree — including shared helpers — with `getContext()`, so there's no need to thread `ctx` through your code.
+Every HTTP handler receives a `ctx` (`TrayContext`); scheduled handlers receive a `ScheduleContext` (see [Scheduled functions](#scheduled-functions)). You can also reach the current context anywhere in the async call tree — including shared helpers — with `getContext()`, so there's no need to thread `ctx` through your code.
 
 | Property | Description |
 |----------|-------------|
@@ -134,6 +135,43 @@ const file = await ctx.files().get('temp/a.json'); // { data, metadata } | null
 
 > `list` returns the immediate children of a prefix.
 
+## Scheduled functions
+
+`functions/_scheduled/` is a reserved namespace for schedule definitions: every module file in it runs on a cron schedule instead of an HTTP route and must default-export `defineSchedule`. Don't create normal HTTP functions there — files in this directory never route:
+
+```typescript
+// functions/_scheduled/daily-report.ts
+import { defineSchedule } from '@trayai/helix-sdk';
+
+export default defineSchedule({
+  cron: '0 6 * * *',           // 5-field standard cron
+  timezone: 'Europe/London',   // IANA timezone name; defaults to UTC
+  handler: async (ctx) => {
+    ctx.log.info('daily report', { firedAt: ctx.trigger.firedAt });
+  },
+});
+```
+
+- **`cron`** is a 5-field standard expression (minute, hour, day-of-month, month, day-of-week). An expression that constrains both day-of-month and day-of-week is rejected at build time — leave one of them `*`.
+- **`timezone`** must be an IANA name (`"Europe/London"`); offset forms (`"+05:00"`) are rejected. Omit it for UTC.
+- The handler receives a `ScheduleContext`: the core `ctx` surface (`ctx.http`, `ctx.http.authed()`, `ctx.kv()`, `ctx.files()`, `ctx.log`, `ctx.config`, `ctx.state`, and the invocation identifiers) plus `ctx.trigger` (a `ScheduleTrigger`):
+
+| Property | Description |
+|----------|-------------|
+| `ctx.trigger.type` | Always `'schedule'` |
+| `ctx.trigger.scheduledAt` | When the cron said the run should fire (`Date`) |
+| `ctx.trigger.firedAt` | When it actually executed (`Date`) |
+| `ctx.trigger.isManual` | `true` when the run was triggered manually rather than by the schedule |
+
+There is no request and no user: the request-derived fields (`ctx.input`, `ctx.method`, `ctx.path`, `ctx.headers`, `ctx.status()`, `ctx.error()`, `ctx.request`, `ctx.identity`) do not exist on a schedule context. Return nothing — there is no response; throwing an error fails the run.
+
+Things to know:
+
+- Schedules fire **on the deployed platform**. The local dev server does not fire them; `helix deploy` registers the schedules present at deploy time.
+- Overlapping runs are possible — write handlers to tolerate running concurrently.
+- Files and directories starting with `_` below `_scheduled/` are treated as helpers, not schedules — the only files that belong in the directory besides schedule definitions.
+- `getContext()` works inside schedule handlers; shared code can detect a scheduled run by checking for `ctx.trigger`.
+
 ## Authentication
 
 Authenticated features (`ctx.http.authed`, `ctx.kv`, `ctx.files`) require you to be logged in during local development:
@@ -218,10 +256,10 @@ The mock context is a Proxy: touching an always-present field (`http`, `db`, `lo
 
 | Import | Contents |
 |--------|----------|
-| `@trayai/helix-sdk` | `defineFunction`, `defineConfig`, `getContext`, `loadConfig`, `requireWorkspaceId`, `createConfigService`, and the public types |
+| `@trayai/helix-sdk` | `defineFunction`, `defineSchedule`, `defineConfig`, `getContext`, `loadConfig`, `requireWorkspaceId`, `createConfigService`, and the public types |
 | `@trayai/helix-sdk/testing` | `runWithContext` |
 
-Key exported types include `TrayContext`, `TrayConfig`, `LoadedTrayConfig`, `HttpClient`, `KeyValueStore`, `FileSystemClient`, `Logger`, `ConfigService`, and `WorkspaceIdRequiredError`.
+Key exported types include `TrayContext`, `ScheduleContext`, `ScheduleTrigger`, `TrayConfig`, `LoadedTrayConfig`, `HttpClient`, `KeyValueStore`, `FileSystemClient`, `Logger`, `ConfigService`, and `WorkspaceIdRequiredError`.
 
 ## Tech stack
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayai/helix-sdk",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "Helix SDK runtime — defineFunction, ctx, defineConfig, authed HTTP",
   "license": "Apache-2.0",
   "author": "trayio",