@trayai/helix-sdk 0.63.0

package/dist/types-BxQmQx3V.d.ts

@@ -0,0 +1,173 @@
+import { H3Event } from 'h3';
+import { KyInstance } from 'ky';
+import { ZodType } from 'zod';
+import { Storage } from 'unstorage';
+
+/** Connection + call params supplied by the caller at `.parameters()` time. */
+interface DbCallParameters {
+    clusterIdentifier?: string;
+    database: string;
+    dbUser?: string;
+    region: string;
+    workgroupName?: string;
+    statementName?: string;
+}
+/** Terminal builder returned by `.parameters(params)`. */
+interface SqlBuilder {
+    sql(query: string): Promise<string>;
+}
+interface DbClient {
+    parameters(params: DbCallParameters): SqlBuilder;
+    sql(query: string): Promise<string>;
+}
+
+type KeyValueStore = Pick<Storage, "getItem" | "setItem" | "removeItem" | "hasItem">;
+
+interface FileMetadata {
+    /** Developer-facing path (no project prefix). */
+    path: string;
+    size: number;
+    contentType: string;
+    lastModified: Date;
+    /**
+     * Custom metadata set via `PutOptions.metadata`.
+     * **Dev only** — the production backend has no field for this; it's silently
+     * dropped in Lambda mode and always comes back empty there.
+     */
+    metadata: Record<string, string>;
+    /**
+     * Content hash. **Dev**: real sha1 of the bytes. **Lambda**: synthesized from
+     * size + lastModified — the backend doesn't expose a content hash, so don't
+     * treat this as a true integrity check in production.
+     */
+    etag: string;
+}
+interface PutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface SignedUrlOptions {
+    expiresIn?: number;
+    contentType?: string;
+    maxSize?: number;
+}
+interface ListOptions {
+    /**
+     * Max children fetched from the backend before client-side filtering to files
+     * only. Subfolders count against this limit too, so a folder with many
+     * subfolders can yield fewer than `limit` files back — this is a backend API
+     * limitation (no filtered count), not a bug in `list()`.
+     */
+    limit?: number;
+    cursor?: string;
+}
+type FileData = Buffer | Uint8Array | ReadableStream | string;
+interface FileSystemClient {
+    put(path: string, data: FileData, opts?: PutOptions): Promise<FileMetadata>;
+    get(path: string): Promise<{
+        data: Buffer;
+        metadata: FileMetadata;
+    } | null>;
+    /**
+     * Returns a POST endpoint for direct-to-backend upload — **not** a raw
+     * PUT-body URL like S3. The caller must POST `multipart/form-data` with the
+     * file part named `fileUploadContentInput` in Lambda mode (dev mode accepts
+     * a plain PUT of raw bytes). See spec 09 deviations.
+     */
+    getUploadUrl(path: string, opts?: SignedUrlOptions): Promise<{
+        url: string;
+        expiresAt: Date;
+    }>;
+    getDownloadUrl(path: string, opts?: SignedUrlOptions): Promise<{
+        url: string;
+        expiresAt: Date;
+    }>;
+    /**
+     * Lists immediate children of the folder resolved from `prefix` — not a
+     * recursive substring-prefix scan. `cursor` is always `null`; the backend
+     * has no offset/cursor support, only `limit`. Results are filtered to files
+     * only after fetching, so `opts.limit` bounds total children (files +
+     * subfolders), not the returned file count — see `ListOptions.limit`.
+     */
+    list(prefix?: string, opts?: ListOptions): Promise<{
+        files: FileMetadata[];
+        cursor: string | null;
+    }>;
+    delete(path: string): Promise<void>;
+    /** Deletes every file under `prefix`'s resolved folder, then the folder itself. */
+    deleteMany(prefix: string): Promise<{
+        deleted: number;
+    }>;
+    head(path: string): Promise<FileMetadata | null>;
+}
+
+interface Logger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+interface BrokerCallOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    timeout?: number;
+}
+interface BrokerCallResult {
+    status: number;
+    body?: unknown;
+    headers: Record<string, string | string[]>;
+}
+interface BrokerAuthedClient {
+    get(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    post(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    put(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    patch(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    delete(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    head(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+    options(url: string, options?: BrokerCallOptions): Promise<BrokerCallResult>;
+}
+interface HttpClient extends KyInstance {
+    authed(alias: string): BrokerAuthedClient;
+}
+interface TrayContext<T = Record<string, unknown>> {
+    input: T;
+    method: string;
+    path: string;
+    headers: Record<string, string | undefined>;
+    http: HttpClient;
+    db(alias: string): DbClient;
+    kv(): KeyValueStore;
+    files(): FileSystemClient;
+    log: Logger;
+    config: Record<string, unknown>;
+    status(code: number): void;
+    error(code: number, message: string): never;
+    state: Record<string, unknown>;
+    request: H3Event;
+    executionId: string;
+    deploymentId: string | null;
+    userId: string | null;
+    /**
+     * Minimal user identity context (spec 15). Production currently carries
+     * only the user ID (invocation payload root in lambda; x-tray-user-id
+     * header in dev) — richer fields (email, name, groups, roles) arrive with
+     * the full identity feature. Null when no user is known.
+     */
+    identity: {
+        user: {
+            id: string;
+        };
+    } | null;
+    traceId: string;
+}
+
+/** Sentinel type — skip input validation when only output validation is desired */
+type UnvalidatedInput = Record<string, unknown>;
+interface DefineFunctionOptions<TInput extends ZodType | undefined = undefined, TOutput extends ZodType | undefined = undefined> {
+    input?: TInput;
+    output?: TOutput;
+}
+type FunctionHandler<T = Record<string, unknown>> = (ctx: TrayContext<T>) => Promise<unknown>;
+
+export type { DbCallParameters as D, FileSystemClient as F, HttpClient as H, KeyValueStore as K, Logger as L, SqlBuilder as S, TrayContext as T, UnvalidatedInput as U, DbClient as a, DefineFunctionOptions as b, FunctionHandler as c };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@trayai/helix-sdk",
+  "version": "0.63.0",
+  "description": "Helix SDK runtime — defineFunction, ctx, defineConfig, authed HTTP",
+  "license": "Apache-2.0",
+  "author": "trayio",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing/index.js",
+      "types": "./dist/testing/index.d.ts"
+    },
+    "./broker": {
+      "import": "./dist/broker/index.js",
+      "types": "./dist/broker/index.d.ts"
+    },
+    "./internal": {
+      "tray-internal": {
+        "types": "./dist/internal/index.d.ts",
+        "import": "./dist/internal/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "0.220.0",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-logs-otlp-proto": "0.220.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "0.220.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "0.220.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "c12": "^3.3.4",
+    "chokidar": "^5.0.0",
+    "h3": "^1.15.11",
+    "ky": "^1.8.1",
+    "unstorage": "^1.17.5",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "eslint": "^9.39.4",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "lint": "tsc --noEmit && eslint ."
+  }
+}