@simpleplatform/sdk 1.1.0 → 1.2.0

package/dist/storage.d.ts

@@ -1,4 +1,30 @@
 import type { Context, DocumentHandle, ExternalFileSource, StorageTarget } from './types';
+/**
+ * Uploads an in-memory binary buffer as a document to the platform's storage system.
+ *
+ * Accepts any binary content (images, PDFs, etc.) as an `ArrayBuffer` or `Uint8Array`.
+ * The bytes are base64-encoded once here at the JSON boundary, decoded on the backend,
+ * and then stored via the same pipeline as `uploadExternal`.
+ *
+ * @param buffer The binary content to upload.
+ * @param filename The filename to assign to the stored document.
+ * @param mimeType The MIME type of the content (e.g. `'application/pdf'`, `'image/png'`).
+ * @param target The target location where the file should be stored.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with a DocumentHandle containing file metadata.
+ *
+ * @example
+ * ```typescript
+ * const handle = await uploadBuffer(
+ *   pdfBytes,
+ *   'report.pdf',
+ *   'application/pdf',
+ *   { app_id: 'dev.simple.system', table_name: 'documents', field_name: 'attachment' },
+ *   context
+ * )
+ * ```
+ */
+export declare function uploadBuffer(buffer: ArrayBuffer | Uint8Array, filename: string, mimeType: string, target: StorageTarget, context: Context): Promise<DocumentHandle>;
 /**
  * Uploads a file from an external URL to the platform's storage system.
  *

package/dist/storage.js

@@ -1,4 +1,49 @@
 import { execute as hostExecute } from './host';
+/**
+ * Uploads an in-memory binary buffer as a document to the platform's storage system.
+ *
+ * Accepts any binary content (images, PDFs, etc.) as an `ArrayBuffer` or `Uint8Array`.
+ * The bytes are base64-encoded once here at the JSON boundary, decoded on the backend,
+ * and then stored via the same pipeline as `uploadExternal`.
+ *
+ * @param buffer The binary content to upload.
+ * @param filename The filename to assign to the stored document.
+ * @param mimeType The MIME type of the content (e.g. `'application/pdf'`, `'image/png'`).
+ * @param target The target location where the file should be stored.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with a DocumentHandle containing file metadata.
+ *
+ * @example
+ * ```typescript
+ * const handle = await uploadBuffer(
+ *   pdfBytes,
+ *   'report.pdf',
+ *   'application/pdf',
+ *   { app_id: 'dev.simple.system', table_name: 'documents', field_name: 'attachment' },
+ *   context
+ * )
+ * ```
+ */
+export async function uploadBuffer(buffer, filename, mimeType, target, context) {
+    if (!filename || filename.trim() === '')
+        throw new Error('filename is required');
+    if (!mimeType || mimeType.trim() === '')
+        throw new Error('mimeType is required');
+    if (!target.app_id || target.app_id.trim() === '')
+        throw new Error('Target app_id is required and cannot be empty');
+    if (!target.table_name || target.table_name.trim() === '')
+        throw new Error('Target table_name is required and cannot be empty');
+    if (!target.field_name || target.field_name.trim() === '')
+        throw new Error('Target field_name is required and cannot be empty');
+    const bytes = buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : buffer;
+    // Base64-encode at the JSON boundary (JSON.stringify cannot carry raw binary)
+    const base64 = btoa(String.fromCharCode(...bytes));
+    const source = { bytes: base64, filename, mime_type: mimeType };
+    const response = await hostExecute('action:storage/upload-external', { source, target }, context);
+    if (!response.ok)
+        throw new Error(response.error?.message ?? 'Buffer upload failed');
+    return response.data;
+}
 /**
  * Uploads a file from an external URL to the platform's storage system.
  *
@@ -32,9 +77,9 @@ import { execute as hostExecute } from './host';
  * ```
  */
 export async function uploadExternal(source, target, context) {
-    // Validate source
-    if (!source.url || source.url.trim() === '') {
-        throw new Error('Source URL is required and cannot be empty');
+    // Validate source: must have either url or bytes
+    if ((!source.url || source.url.trim() === '') && !source.bytes) {
+        throw new Error('Either source URL or bytes must be provided');
     }
     // Validate target
     if (!target.app_id || target.app_id.trim() === '') {

package/dist/types.d.ts

@@ -20,9 +20,9 @@ export interface DocumentHandle {
     /** The storage path where the file is stored. */
     storage_path: string;
 }
-/** Represents the source configuration for downloading an external file. */
+/** Represents the source configuration for an external file upload (URL or in-memory bytes). */
 export interface ExternalFileSource {
-    /** Optional authentication configuration for accessing the external file. */
+    /** Optional authentication configuration for accessing the external file (URL path only). */
     auth?: {
         /** Bearer token for bearer authentication. */
         bearer_token?: string;
@@ -33,8 +33,17 @@ export interface ExternalFileSource {
         /** Username for basic authentication. */
         username?: string;
     };
-    /** The URL of the external file to download. */
-    url: string;
+    /**
+     * Base64-encoded binary content for in-memory uploads.
+     * Use this with `filename` and `mime_type` instead of `url`.
+     */
+    bytes?: string;
+    /** Original filename — required when using `bytes`. */
+    filename?: string;
+    /** MIME type of the file — required when using `bytes`. */
+    mime_type?: string;
+    /** The URL of the external file to download. Mutually exclusive with `bytes`. */
+    url?: string;
 }
 /** Contains metadata about the specific logic execution. */
 export interface Logic {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",
@@ -61,10 +61,10 @@
     "dist"
   ],
   "dependencies": {
-    "esbuild": "0.27.3"
+    "esbuild": "0.27.4"
   },
   "devDependencies": {
-    "@types/node": "25.3.3",
+    "@types/node": "25.5.0",
     "typescript": "5.9.3"
   },
   "scripts": {