@simpleplatform/sdk 1.0.0

package/dist/settings.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from './types';
+/**
+ * Retrieves application settings for the specified keys.
+ * This function communicates with the host system's settings action and returns
+ * a map of the requested settings.
+ *
+ * @param appId The application identifier for which to retrieve settings.
+ * @param keys An array of setting keys to retrieve.
+ * @param context The execution context.
+ * @returns A promise that resolves with a map containing the requested settings.
+ * @throws Will throw an error if the request fails or the host returns an error.
+ */
+export declare function get(appId: string, keys: string[], context: Context): Promise<Record<string, any>>;

package/dist/settings.js

@@ -0,0 +1,25 @@
+import { execute as hostExecute } from './host';
+/**
+ * Retrieves application settings for the specified keys.
+ * This function communicates with the host system's settings action and returns
+ * a map of the requested settings.
+ *
+ * @param appId The application identifier for which to retrieve settings.
+ * @param keys An array of setting keys to retrieve.
+ * @param context The execution context.
+ * @returns A promise that resolves with a map containing the requested settings.
+ * @throws Will throw an error if the request fails or the host returns an error.
+ */
+export async function get(appId, keys, context) {
+    if (!appId) {
+        throw new Error('appId is required for settings retrieval');
+    }
+    if (!keys || keys.length === 0) {
+        throw new Error('setting keys are required for settings retrieval');
+    }
+    const response = await hostExecute('action:settings/get', { app_id: appId, keys }, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message ?? 'Settings retrieval failed');
+    }
+    return response.data;
+}

package/dist/storage.d.ts

@@ -0,0 +1,34 @@
+import type { Context, DocumentHandle, ExternalFileSource, StorageTarget } from './types';
+/**
+ * Uploads a file from an external URL to the platform's storage system.
+ *
+ * This function downloads a file from the specified external source and uploads it
+ * to the target location in the platform's storage. The file is content-addressed
+ * using SHA-256 hashing, enabling automatic deduplication.
+ *
+ * @param source The external file source configuration including URL and optional authentication.
+ * @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.
+ * @throws Will throw an error if validation fails or the upload operation fails.
+ *
+ * @example
+ * ```typescript
+ * const handle = await uploadExternal(
+ *   {
+ *     url: 'https://example.com/document.pdf',
+ *     auth: {
+ *       type: 'bearer',
+ *       bearer_token: 'your-token-here'
+ *     }
+ *   },
+ *   {
+ *     app_id: 'dev.simple.system',
+ *     table_name: 'documents',
+ *     field_name: 'attachment'
+ *   },
+ *   context
+ * );
+ * ```
+ */
+export declare function uploadExternal(source: ExternalFileSource, target: StorageTarget, context: Context): Promise<DocumentHandle>;

package/dist/storage.js

@@ -0,0 +1,72 @@
+import { execute as hostExecute } from './host';
+/**
+ * Uploads a file from an external URL to the platform's storage system.
+ *
+ * This function downloads a file from the specified external source and uploads it
+ * to the target location in the platform's storage. The file is content-addressed
+ * using SHA-256 hashing, enabling automatic deduplication.
+ *
+ * @param source The external file source configuration including URL and optional authentication.
+ * @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.
+ * @throws Will throw an error if validation fails or the upload operation fails.
+ *
+ * @example
+ * ```typescript
+ * const handle = await uploadExternal(
+ *   {
+ *     url: 'https://example.com/document.pdf',
+ *     auth: {
+ *       type: 'bearer',
+ *       bearer_token: 'your-token-here'
+ *     }
+ *   },
+ *   {
+ *     app_id: 'dev.simple.system',
+ *     table_name: 'documents',
+ *     field_name: 'attachment'
+ *   },
+ *   context
+ * );
+ * ```
+ */
+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 target
+    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');
+    }
+    // Validate auth if provided
+    if (source.auth) {
+        if (source.auth.type !== 'basic' && source.auth.type !== 'bearer') {
+            throw new Error('Auth type must be either "basic" or "bearer"');
+        }
+        if (source.auth.type === 'bearer' && (!source.auth.bearer_token || source.auth.bearer_token.trim() === '')) {
+            throw new Error('Bearer token is required when auth type is "bearer"');
+        }
+        if (source.auth.type === 'basic') {
+            if (!source.auth.username || source.auth.username.trim() === '') {
+                throw new Error('Username is required when auth type is "basic"');
+            }
+            if (!source.auth.password || source.auth.password.trim() === '') {
+                throw new Error('Password is required when auth type is "basic"');
+            }
+        }
+    }
+    // Call the host function
+    const response = await hostExecute('action:storage/upload-external', { source, target }, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message ?? 'External file upload failed');
+    }
+    return response.data;
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/** The complete execution context for an action. */
+export interface Context {
+    logic: Logic;
+    tenant: Tenant;
+    user: User;
+}
+/**
+ * Represents the metadata handle for a file securely stored in the platform.
+ * This JSON object is the "pointer" to the file and is stored in `:document` fields.
+ */
+export interface DocumentHandle {
+    /** The SHA-256 hash of the file content, used as the unique content-addressable key. */
+    file_hash: string;
+    /** The original name of the file when it was uploaded. */
+    filename: string;
+    /** The type of the file, e.g., "application/pdf". */
+    mime_type: string;
+    /** The size of the file in bytes. */
+    size: number;
+    /** The storage path where the file is stored. */
+    storage_path: string;
+}
+/** Represents the source configuration for downloading an external file. */
+export interface ExternalFileSource {
+    /** Optional authentication configuration for accessing the external file. */
+    auth?: {
+        /** Bearer token for bearer authentication. */
+        bearer_token?: string;
+        /** Password for basic authentication. */
+        password?: string;
+        /** The type of authentication to use. */
+        type: 'basic' | 'bearer';
+        /** Username for basic authentication. */
+        username?: string;
+    };
+    /** The URL of the external file to download. */
+    url: string;
+}
+/** Contains metadata about the specific logic execution. */
+export interface Logic {
+    execution_env: string;
+    execution_id: string;
+    id: string;
+    trigger_id: string;
+}
+/** Error structure for host communication responses. */
+export interface SimpleError {
+    message: string;
+    reasons?: string[];
+}
+/** The low-level request structure sent by the host to an action. */
+export interface SimpleRequest {
+    context: Context;
+    data?: string;
+    headers: Record<string, any>;
+}
+/** The low-level response structure for host communication. */
+export interface SimpleResponse<T = any> {
+    data?: T;
+    error?: SimpleError;
+    ok: boolean;
+}
+/** Represents the target location for storing an uploaded file. */
+export interface StorageTarget {
+    /** The application ID where the file will be stored. */
+    app_id: string;
+    /** The field name where the DocumentHandle will be stored. */
+    field_name: string;
+    /** The table name where the record exists. */
+    table_name: string;
+}
+/** Represents tenant information in the execution context. */
+export interface Tenant {
+    host?: string;
+    id?: string;
+    name: string;
+}
+/** Represents user information in the execution context. */
+export interface User {
+    id?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker-override.js

@@ -0,0 +1,86 @@
+/**
+ * @file SDK Worker Override Module.
+ * This file exports worker-compatible implementations of `execute` and
+ * `executeAsync`. The SDK's build tool will use esbuild's `alias` feature
+ * to replace the original `@simple/sdk/host` module with this one during
+ * the async application build.
+ */
+
+// State and listeners are sandboxed within this module's closure.
+const pendingHostRequests = new Map()
+
+// eslint-disable-next-line no-restricted-globals
+self.addEventListener('message', (event) => {
+  const message = event && event.data
+  if (
+    typeof message !== 'object'
+    || message === null
+    || message.type !== 'host_response'
+  ) {
+    return
+  }
+
+  const pending = pendingHostRequests.get(message.requestId)
+  if (!pending)
+    return
+
+  message.response.ok
+    ? pending.resolve(message.response)
+    : pending.reject(new Error(message.response.error ?? 'Unknown host error'))
+
+  pendingHostRequests.delete(message.requestId)
+})
+
+/**
+ * Worker-compatible implementation that returns a Promise and uses postMessage.
+ * @returns {Promise<import('./types').SimpleResponse<any>>} A promise that resolves with the host response
+ */
+export function execute(actionName, params, context) {
+  return new Promise((resolve, reject) => {
+    const requestId = crypto.randomUUID()
+    pendingHostRequests.set(requestId, { reject, resolve })
+
+    const hostRequest = {
+      context,
+      executionId: context.logic.execution_id,
+      name: actionName,
+      params,
+      type: 'hostRequest',
+    }
+
+    // eslint-disable-next-line no-restricted-globals
+    self.postMessage({
+      request: hostRequest,
+      requestId,
+      type: 'host_request',
+    })
+  })
+}
+
+/**
+ * Worker-compatible fire-and-forget implementation.
+ */
+export function executeAsync(actionName, params, context) {
+  const hostRequest = {
+    context,
+    executionId: context.logic.execution_id,
+    name: actionName,
+    params,
+    type: 'hostRequest',
+  }
+
+  // eslint-disable-next-line no-restricted-globals
+  self.postMessage({
+    request: hostRequest,
+    type: 'host_cast',
+  })
+}
+
+/**
+ * This module replaces host.ts, which also exports getContext.
+ * We provide a stub here, as it's not used in the worker context.
+ */
+export function getContext() {
+  console.warn('getContext() was called in a script worker context, which is not supported.')
+  return new Uint8Array(0)
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@simpleplatform/sdk",
+  "version": "1.0.0",
+  "description": "Simple Platform Typescript SDK",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "default": "./dist/ai.js"
+    },
+    "./graphql": {
+      "types": "./dist/graphql.d.ts",
+      "default": "./dist/graphql.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "default": "./dist/settings.js"
+    },
+    "./security": {
+      "types": "./dist/security.d.ts",
+      "default": "./dist/security.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "default": "./dist/host.js"
+    },
+    "./worker": "./dist/worker-override.js",
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "simple-sdk-build": "./dist/build.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "esbuild": "0.27.2"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.3",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && cp src/worker-override.js dist/ && cp cli/build.js dist/"
+  }
+}