@simpleplatform/sdk 1.0.4 → 1.2.0

package/dist/ai.d.ts

@@ -157,6 +157,21 @@ export interface AITranscribeOptions extends Omit<AICommonOptions, 'prompt'> {
      */
     summarize?: boolean;
 }
+/**
+ * Options for searching faces within the Face Engine.
+ */
+export interface AIFaceSearchOptions {
+    /**
+     * Maximum number of matches to return.
+     * Defaults to 5.
+     */
+    maxFaces?: number;
+    /**
+     * Minimum similarity percentage (0-100) required for a match.
+     * Defaults to 85.0.
+     */
+    similarityThreshold?: number;
+}
 /**
  * The response structure from a successful AI `extract` or `summarize` operation.
  */
@@ -236,4 +251,38 @@ export declare function summarize(input: DocumentHandle | object | string, optio
  * // Returns: { language: "en", summary: "...", participants: ["Participant 1", "Participant 2"] }
  */
 export declare function transcribe(input: DocumentHandle, options: AITranscribeOptions, context: Context): Promise<AIExecutionResult>;
+/**
+ * Enrolls a face for a subject. The face is associated with the given `subjectId`
+ * within the tenant's secure collection.
+ *
+ * @param subjectId A unique identifier for the subject (e.g., employee ID, user ID).
+ * @param image The image containing the face to enroll. Can be a base64 string or a DocumentHandle.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an object containing the enrolled `face_id`.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ */
+export declare function enrollFace(subjectId: string, image: DocumentHandle | string, context: Context): Promise<{
+    face_id: string;
+}>;
+/**
+ * Searches for faces matching the provided image within the tenant's collection.
+ *
+ * @param image The image to search for. Can be a base64 string or a DocumentHandle.
+ * @param options Configuration for the search operation (e.g., maxFaces, similarityThreshold).
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to a list of matching faces and their confidence scores.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ */
+export declare function searchFace(image: DocumentHandle | string, options: AIFaceSearchOptions | undefined, context: Context): Promise<any>;
+/**
+ * Deletes one or more faces from the tenant's collection by their face IDs.
+ *
+ * @param faceIds An array of face IDs to delete.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an object indicating the IDs of successfully deleted faces.
+ * @throws Will throw an error if the operation fails.
+ */
+export declare function deleteFace(faceIds: string[], context: Context): Promise<{
+    deleted: string[];
+}>;
 export {};

package/dist/ai.js

@@ -263,3 +263,109 @@ export async function transcribe(input, options, context) {
         schema,
     }, context);
 }
+// ============================================================================
+// Face Recognition API
+// ============================================================================
+let _collectionEnsured = false;
+/**
+ * Internal helper to ensure the face collection exists before making face operations.
+ * Caches the result per Javascript isolate execution to minimize RPC overhead over
+ * sequential calls in the same logic.
+ */
+async function _ensureFaceCollection(context) {
+    if (_collectionEnsured)
+        return;
+    const response = await hostExecute('action:ai/face/ensure-collection', {}, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message || 'Failed to ensure face collection.');
+    }
+    _collectionEnsured = true;
+}
+/**
+ * Enrolls a face for a subject. The face is associated with the given `subjectId`
+ * within the tenant's secure collection.
+ *
+ * @param subjectId A unique identifier for the subject (e.g., employee ID, user ID).
+ * @param image The image containing the face to enroll. Can be a base64 string or a DocumentHandle.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an object containing the enrolled `face_id`.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ */
+export async function enrollFace(subjectId, image, context) {
+    if (!subjectId) {
+        throw new Error('The `subjectId` parameter is required for `enrollFace`.');
+    }
+    if (!image) {
+        throw new Error('The `image` parameter is required for `enrollFace`.');
+    }
+    // Ensure the tenant's collection is ready before enrolling
+    await _ensureFaceCollection(context);
+    // Upload pending documents if given handles
+    const processedImage = await _uploadPendingFiles(image, context);
+    const payload = {
+        image: processedImage,
+        subject_id: subjectId,
+    };
+    const response = await hostExecute('action:ai/face/enroll', payload, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message || 'Face enrollment failed.');
+    }
+    return response.data;
+}
+/**
+ * Searches for faces matching the provided image within the tenant's collection.
+ *
+ * @param image The image to search for. Can be a base64 string or a DocumentHandle.
+ * @param options Configuration for the search operation (e.g., maxFaces, similarityThreshold).
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to a list of matching faces and their confidence scores.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ */
+export async function searchFace(image, options = {}, context) {
+    if (!image) {
+        throw new Error('The `image` parameter is required for `searchFace`.');
+    }
+    // Ensure collection exists before searching
+    await _ensureFaceCollection(context);
+    const processedImage = await _uploadPendingFiles(image, context);
+    // Map JS property names to Elixir convention if needed, though they are passed as options
+    // and parsed correctly in simple_logic if expected.
+    // The simple_ai FaceEngine expects snake_case for options like max_faces or similarity_threshold.
+    const mappedOptions = {};
+    if (options.maxFaces !== undefined)
+        mappedOptions.max_faces = options.maxFaces;
+    if (options.similarityThreshold !== undefined)
+        mappedOptions.similarity_threshold = options.similarityThreshold;
+    const payload = {
+        image: processedImage,
+        options: mappedOptions,
+    };
+    const response = await hostExecute('action:ai/face/search', payload, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message || 'Face search failed.');
+    }
+    return response.data;
+}
+/**
+ * Deletes one or more faces from the tenant's collection by their face IDs.
+ *
+ * @param faceIds An array of face IDs to delete.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an object indicating the IDs of successfully deleted faces.
+ * @throws Will throw an error if the operation fails.
+ */
+export async function deleteFace(faceIds, context) {
+    if (!faceIds || !Array.isArray(faceIds) || faceIds.length === 0) {
+        throw new Error('The `faceIds` parameter must be a non-empty array for `deleteFace`.');
+    }
+    await _ensureFaceCollection(context);
+    const payload = {
+        face_ids: faceIds,
+    };
+    const response = await hostExecute('action:ai/face/delete', payload, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message || 'Face deletion failed.');
+    }
+    // Ensure consistent return format
+    return { deleted: Array.isArray(response.data) ? response.data : response.data?.deleted || [] };
+}

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/dist/worker-override.js

@@ -11,22 +11,21 @@ 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'
-  ) {
+  const message = event.data
+  if (message.type !== 'host_response')
     return
-  }
 
   const pending = pendingHostRequests.get(message.requestId)
   if (!pending)
     return
 
+  const errorMsg = typeof message.response.error === 'object' && message.response.error?.message
+    ? message.response.error.message
+    : message.response.error ?? 'Unknown host error'
+
   message.response.ok
     ? pending.resolve(message.response)
-    : pending.reject(new Error(message.response.error ?? 'Unknown host error'))
+    : pending.reject(new Error(errorMsg))
 
   pendingHostRequests.delete(message.requestId)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "1.0.4",
+  "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.2"
+    "esbuild": "0.27.4"
   },
   "devDependencies": {
-    "@types/node": "25.2.0",
+    "@types/node": "25.5.0",
     "typescript": "5.9.3"
   },
   "scripts": {