@trayio/cdk-dsl 6.0.0 → 6.2.0-unstable.38a8cdc

package/README.md

@@ -1482,6 +1482,79 @@ export const myOperationHandler =
     );
 ```
 
+### Handling files in composite operations
+
+Composite handlers receive a fourth argument, `runtime`, with Promise-based file handling under `runtime.files`. Use it when an operation produces or transforms bytes in memory (for example resizing an image, or zipping the output of several operations) and needs to return them as a `FileReference`, or when it needs to read the content of a `FileReference` it received as input.
+
+```typescript
+import { FileReference } from '@trayio/cdk-dsl/dist/connector/operation/OperationHandler';
+import {
+	FileUpload,
+	FileDownload,
+	OperationHandlerRuntime,
+} from '@trayio/cdk-dsl/dist/connector/operation/OperationHandlerRuntime';
+
+type FileUpload = {
+	name: string;
+	contentType: string;
+	content: Readable | Buffer;
+	size?: number; // optional for streams, lets the runtime tune the upload; derived for Buffers
+};
+
+type FileDownload = {
+	stream: Readable;
+	size?: number;
+	contentType?: string;
+};
+
+type OperationHandlerRuntime = {
+	files: {
+		upload(file: FileUpload): Promise<FileReference>;
+		download(file: FileReference): Promise<FileDownload>;
+	};
+};
+```
+
+- `runtime.files.download(fileReference)` resolves the reference to a readable stream (plus `size` and `contentType` when known).
+- `runtime.files.upload({ name, contentType, content })` writes a `Readable` or `Buffer` to Tray file storage and returns a `FileReference` that can be returned as operation output or passed to other operations.
+
+```typescript
+// input.ts
+import { FileReference } from '@trayio/cdk-dsl/dist/connector/operation/OperationHandler';
+
+export type ResizeImageInput = {
+	file: FileReference;
+	width: number;
+};
+```
+
+```typescript
+// output.ts
+import { FileReference } from '@trayio/cdk-dsl/dist/connector/operation/OperationHandler';
+
+export type ResizeImageOutput = {
+	file: FileReference;
+};
+```
+
+```typescript
+// handler.ts
+handler.usingComposite(async (ctx, input, invoke, runtime) => {
+	const { stream } = await runtime.files.download(input.file);
+	const resized = stream.pipe(sharp().resize(input.width));
+	const file = await runtime.files.upload({
+		name: input.file.name,
+		contentType: input.file.mime_type,
+		content: resized,
+	});
+	return OperationHandlerResult.success({ file });
+});
+```
+
+If an upload or download fails, the returned promise rejects with an `Error`. A rejection that the handler does not catch is reported as a connector error, exactly like any other exception thrown from a composite handler. The `runtime` argument is optional to declare: existing three-argument composite handlers keep working unchanged.
+
+When handler tests run through the CDK test runner, composite operations get a local filesystem-backed file storage automatically, so uploads and downloads round-trip without any extra setup.
+
 ### How to enable / disable raw http operation.
 
 By default, all the connectors come with a Raw Http Operation. You can disable it by updating the config in the connector.json

package/dist/connector/operation/CompositeOperationHandler.d.ts

@@ -1,6 +1,7 @@
 import { OperationHandlerAuth, OperationHandlerContext, OperationHandlerResult } from './OperationHandler';
 import { OperationHandlerInvocation } from './OperationHandlerInvocation';
-export type CompositeOperationHandlerFunction<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT> = (ctx: OperationHandlerContext<AUTH>, input: IN, invoke: OperationHandlerInvocation<AUTH>) => Promise<OperationHandlerResult<OUT>>;
+import { OperationHandlerRuntime } from './OperationHandlerRuntime';
+export type CompositeOperationHandlerFunction<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT> = (ctx: OperationHandlerContext<AUTH>, input: IN, invoke: OperationHandlerInvocation<AUTH>, runtime: OperationHandlerRuntime) => Promise<OperationHandlerResult<OUT>>;
 export declare class CompositeOperationHandler<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT> {
     readonly _tag: 'CompositeOperationHandler';
     readonly handlerFunction: CompositeOperationHandlerFunction<AUTH, IN, OUT>;

package/dist/connector/operation/CompositeOperationHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeOperationHandler.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAE1E,MAAM,MAAM,iCAAiC,CAC5C,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG,IACA,CACH,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAClC,KAAK,EAAE,EAAE,EACT,MAAM,EAAE,0BAA0B,CAAC,IAAI,CAAC,KACpC,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1C,qBAAa,yBAAyB,CACrC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG;IAEH,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAA+B;IACzE,QAAQ,CAAC,eAAe,EAAE,iCAAiC,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;gBAG1E,eAAe,EAAE,iCAAiC,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;CAIlE"}
+{"version":3,"file":"CompositeOperationHandler.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,MAAM,MAAM,iCAAiC,CAC5C,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG,IACA,CACH,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAClC,KAAK,EAAE,EAAE,EACT,MAAM,EAAE,0BAA0B,CAAC,IAAI,CAAC,EACxC,OAAO,EAAE,uBAAuB,KAC5B,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1C,qBAAa,yBAAyB,CACrC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG;IAEH,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAA+B;IACzE,QAAQ,CAAC,eAAe,EAAE,iCAAiC,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;gBAG1E,eAAe,EAAE,iCAAiC,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;CAIlE"}

package/dist/connector/operation/OperationHandlerRuntime.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Readable } from 'stream';
+import { FileReference } from './OperationHandler';
+/**
+ * A file produced by a composite operation that should be written to Tray
+ * file storage. `content` may be a stream or an in-memory buffer; for a
+ * buffer `size` is derived automatically, for a stream it is optional but
+ * lets the runtime tune the multipart upload.
+ */
+export type FileUpload = {
+    name: string;
+    contentType: string;
+    content: Readable | Buffer;
+    size?: number;
+};
+/**
+ * The content of a `FileReference` resolved by the runtime.
+ */
+export type FileDownload = {
+    stream: Readable;
+    size?: number;
+    contentType?: string;
+};
+/**
+ * Promise-based file handling exposed to composite operation handlers.
+ * A rejected promise is mapped to a connector error by the runtime if the
+ * handler does not catch it.
+ */
+export type FileHandling = {
+    upload(file: FileUpload): Promise<FileReference>;
+    download(file: FileReference): Promise<FileDownload>;
+};
+/**
+ * Runtime services injected as the fourth argument of a composite operation
+ * handler. Unlike `ctx`, this is not a serialisable value: it is implemented
+ * and provided by `@trayio/cdk-runtime`.
+ */
+export type OperationHandlerRuntime = {
+    files: FileHandling;
+};
+//# sourceMappingURL=OperationHandlerRuntime.d.ts.map

package/dist/connector/operation/OperationHandlerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationHandlerRuntime.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/OperationHandlerRuntime.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACrD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACrC,KAAK,EAAE,YAAY,CAAC;CACpB,CAAC"}

package/dist/connector/operation/OperationHandlerRuntime.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayio/cdk-dsl",
-  "version": "6.0.0",
+  "version": "6.2.0-unstable.38a8cdc",
   "description": "A DSL for connector development",
   "exports": {
     "./*": "./dist/*.js"
@@ -14,7 +14,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trayio/commons": "6.0.0",
+    "@trayio/commons": "6.2.0-unstable.38a8cdc",
     "fp-ts": "2.12.3"
   },
   "typesVersions": {