@squaredr/fieldcraft-supabase 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present SquaredR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @squaredr/fieldcraft-supabase
+
+Supabase storage adapter for [FieldCraft](https://squaredr.tech/products/fieldcraft). Stores form responses in Supabase with optional field-level AES-256-GCM encryption and row-level security support.
+
+## Install
+
+```bash
+npm install @squaredr/fieldcraft-supabase @supabase/supabase-js
+```
+
+**Peer dependencies:** Requires `@squaredr/fieldcraft-core` v1.0.0+ and `@supabase/supabase-js` v2.0+.
+
+## Quick Start
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import { createSupabaseAdapter } from '@squaredr/fieldcraft-supabase'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL,
+  process.env.SUPABASE_ANON_KEY,
+)
+
+const adapter = createSupabaseAdapter({
+  client: supabase,
+  table: 'formengine_responses', // default
+})
+```
+
+Pass the adapter to your form engine's `onSubmit`:
+
+```tsx
+<FormEngineRenderer
+  schema={schema}
+  onSubmit={(response) => adapter.submit(response)}
+/>
+```
+
+## Field-Level Encryption
+
+Encrypt specific fields while leaving others in plaintext (useful for searching non-sensitive columns):
+
+```typescript
+const adapter = createSupabaseAdapter({
+  client: supabase,
+  encryptionKey: process.env.ENCRYPTION_KEY, // 32-byte hex string
+  encryptFields: ['ssn', 'date_of_birth', 'medical_record'],
+})
+```
+
+You can also use the encryption utilities directly:
+
+```typescript
+import { encryptFields, decryptFields } from '@squaredr/fieldcraft-supabase'
+
+const encrypted = encryptFields(values, ['ssn', 'dob'], key)
+const decrypted = decryptFields(encrypted, ['ssn', 'dob'], key)
+```
+
+## Draft Persistence
+
+Save and resume in-progress forms:
+
+```typescript
+import { createSupabaseDraftAdapter } from '@squaredr/fieldcraft-supabase'
+
+const draftAdapter = createSupabaseDraftAdapter({
+  client: supabase,
+})
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `client` | `SupabaseClient` | Yes | Supabase client instance |
+| `table` | `string` | No | Table name (default: `formengine_responses`) |
+| `encryptionKey` | `string` | No | 32-byte hex key for AES-256-GCM |
+| `encryptFields` | `string[]` | No | Field names to encrypt |
+| `onSuccess` | `(response, values) => void` | No | Callback after successful insert |
+| `onError` | `(error) => void` | No | Callback on insert failure |
+
+## Row-Level Security
+
+The adapter is compatible with Supabase RLS policies. Configure your table's RLS rules to control which users can read/write responses.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { FormResponse, SubmitAdapter, DraftAdapter } from '@squaredr/fieldcraft-core';
+
+type SupabaseAdapterConfig = {
+    /** Supabase client instance from @supabase/supabase-js */
+    client: SupabaseClient;
+    /** Table name for responses (default: "formengine_responses") */
+    table?: string;
+    /** Field IDs to encrypt at rest */
+    encryptFields?: string[];
+    /** Base64-encoded 32-byte encryption key */
+    encryptionKey?: string;
+    /** Called after successful insert */
+    onSuccess?: (response: FormResponse, record: unknown) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+};
+type SupabaseDraftAdapterConfig = {
+    /** Supabase client instance */
+    client: SupabaseClient;
+    /** Table name for drafts (default: "formengine_drafts") */
+    table?: string;
+    /** Draft time-to-live in hours (default: 72) */
+    ttlHours?: number;
+};
+/** Minimal Supabase client shape so we don't require the full dependency */
+type SupabaseClient = {
+    from(table: string): SupabaseQueryBuilder;
+};
+type SupabaseQueryBuilder = {
+    insert(values: Record<string, unknown>): SupabaseFilterBuilder;
+    select(columns?: string): SupabaseFilterBuilder;
+    upsert(values: Record<string, unknown>, options?: {
+        onConflict?: string;
+    }): SupabaseFilterBuilder;
+    delete(): SupabaseFilterBuilder;
+};
+type SupabaseFilterBuilder = {
+    eq(column: string, value: unknown): SupabaseFilterBuilder;
+    gt(column: string, value: unknown): SupabaseFilterBuilder;
+    single(): Promise<{
+        data: Record<string, unknown> | null;
+        error: Error | null;
+    }>;
+    then(resolve: (value: {
+        data: unknown;
+        error: Error | null;
+    }) => void): Promise<void>;
+    [Symbol.toStringTag]?: string;
+};
+
+/** Create a Supabase submit adapter. */
+declare function createSupabaseAdapter(config: SupabaseAdapterConfig): SubmitAdapter;
+
+/** Create a Supabase draft adapter. */
+declare function createSupabaseDraftAdapter(config: SupabaseDraftAdapterConfig): DraftAdapter;
+
+/** Encrypt specified fields in a values object. */
+declare function encryptFields(values: Record<string, unknown>, fieldIds: string[], keyBase64: string): Record<string, unknown>;
+/** Decrypt specified fields in a values object. */
+declare function decryptFields(values: Record<string, unknown>, fieldIds: string[], keyBase64: string): Record<string, unknown>;
+
+export { type SupabaseAdapterConfig, type SupabaseClient, type SupabaseDraftAdapterConfig, createSupabaseAdapter, createSupabaseDraftAdapter, decryptFields, encryptFields };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { FormResponse, SubmitAdapter, DraftAdapter } from '@squaredr/fieldcraft-core';
+
+type SupabaseAdapterConfig = {
+    /** Supabase client instance from @supabase/supabase-js */
+    client: SupabaseClient;
+    /** Table name for responses (default: "formengine_responses") */
+    table?: string;
+    /** Field IDs to encrypt at rest */
+    encryptFields?: string[];
+    /** Base64-encoded 32-byte encryption key */
+    encryptionKey?: string;
+    /** Called after successful insert */
+    onSuccess?: (response: FormResponse, record: unknown) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+};
+type SupabaseDraftAdapterConfig = {
+    /** Supabase client instance */
+    client: SupabaseClient;
+    /** Table name for drafts (default: "formengine_drafts") */
+    table?: string;
+    /** Draft time-to-live in hours (default: 72) */
+    ttlHours?: number;
+};
+/** Minimal Supabase client shape so we don't require the full dependency */
+type SupabaseClient = {
+    from(table: string): SupabaseQueryBuilder;
+};
+type SupabaseQueryBuilder = {
+    insert(values: Record<string, unknown>): SupabaseFilterBuilder;
+    select(columns?: string): SupabaseFilterBuilder;
+    upsert(values: Record<string, unknown>, options?: {
+        onConflict?: string;
+    }): SupabaseFilterBuilder;
+    delete(): SupabaseFilterBuilder;
+};
+type SupabaseFilterBuilder = {
+    eq(column: string, value: unknown): SupabaseFilterBuilder;
+    gt(column: string, value: unknown): SupabaseFilterBuilder;
+    single(): Promise<{
+        data: Record<string, unknown> | null;
+        error: Error | null;
+    }>;
+    then(resolve: (value: {
+        data: unknown;
+        error: Error | null;
+    }) => void): Promise<void>;
+    [Symbol.toStringTag]?: string;
+};
+
+/** Create a Supabase submit adapter. */
+declare function createSupabaseAdapter(config: SupabaseAdapterConfig): SubmitAdapter;
+
+/** Create a Supabase draft adapter. */
+declare function createSupabaseDraftAdapter(config: SupabaseDraftAdapterConfig): DraftAdapter;
+
+/** Encrypt specified fields in a values object. */
+declare function encryptFields(values: Record<string, unknown>, fieldIds: string[], keyBase64: string): Record<string, unknown>;
+/** Decrypt specified fields in a values object. */
+declare function decryptFields(values: Record<string, unknown>, fieldIds: string[], keyBase64: string): Record<string, unknown>;
+
+export { type SupabaseAdapterConfig, type SupabaseClient, type SupabaseDraftAdapterConfig, createSupabaseAdapter, createSupabaseDraftAdapter, decryptFields, encryptFields };

package/dist/index.js

@@ -0,0 +1,175 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSupabaseAdapter: () => createSupabaseAdapter,
+  createSupabaseDraftAdapter: () => createSupabaseDraftAdapter,
+  decryptFields: () => decryptFields,
+  encryptFields: () => encryptFields
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/encryption.ts
+var import_node_crypto = __toESM(require("crypto"));
+var IV_LENGTH = 12;
+var AUTH_TAG_LENGTH = 16;
+function parseKey(keyBase64) {
+  const key = Buffer.from(keyBase64, "base64");
+  if (key.length !== 32) {
+    throw new Error("Encryption key must be exactly 32 bytes (base64-encoded)");
+  }
+  return key;
+}
+function encryptValue(plaintext, key) {
+  const iv = import_node_crypto.default.randomBytes(IV_LENGTH);
+  const cipher = import_node_crypto.default.createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final()
+  ]);
+  const authTag = cipher.getAuthTag();
+  return Buffer.concat([iv, encrypted, authTag]).toString("base64");
+}
+function decryptValue(encoded, key) {
+  const buf = Buffer.from(encoded, "base64");
+  const iv = buf.subarray(0, IV_LENGTH);
+  const authTag = buf.subarray(buf.length - AUTH_TAG_LENGTH);
+  const ciphertext = buf.subarray(IV_LENGTH, buf.length - AUTH_TAG_LENGTH);
+  const decipher = import_node_crypto.default.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+  return decipher.update(ciphertext) + decipher.final("utf8");
+}
+function encryptFields(values, fieldIds, keyBase64) {
+  const key = parseKey(keyBase64);
+  const result = { ...values };
+  for (const fieldId of fieldIds) {
+    if (result[fieldId] !== void 0 && result[fieldId] !== null) {
+      result[fieldId] = encryptValue(
+        JSON.stringify(result[fieldId]),
+        key
+      );
+    }
+  }
+  return result;
+}
+function decryptFields(values, fieldIds, keyBase64) {
+  const key = parseKey(keyBase64);
+  const result = { ...values };
+  for (const fieldId of fieldIds) {
+    if (typeof result[fieldId] === "string") {
+      result[fieldId] = JSON.parse(
+        decryptValue(result[fieldId], key)
+      );
+    }
+  }
+  return result;
+}
+
+// src/supabase-adapter.ts
+function createSupabaseAdapter(config) {
+  return {
+    name: "supabase",
+    async submit(response) {
+      let values = { ...response.values };
+      if (config.encryptFields?.length && config.encryptionKey) {
+        values = encryptFields(
+          values,
+          config.encryptFields,
+          config.encryptionKey
+        );
+      }
+      const { error } = await config.client.from(config.table ?? "formengine_responses").insert({
+        schema_id: response.schemaId,
+        schema_version: response.schemaVersion,
+        session_token: response.sessionToken,
+        data: values,
+        metadata: response.metadata,
+        completion_time_ms: response.completionTimeMs,
+        submitted_at: response.submittedAt
+      });
+      if (error) {
+        const err = new Error(`Supabase insert failed: ${error.message}`);
+        config.onError?.(err);
+        throw err;
+      }
+      config.onSuccess?.(response, values);
+    },
+    onError: config.onError
+  };
+}
+
+// src/supabase-draft-adapter.ts
+function createSupabaseDraftAdapter(config) {
+  const tableName = config.table ?? "formengine_drafts";
+  const ttlHours = config.ttlHours ?? 72;
+  return {
+    async save(draft) {
+      const expiresAt = new Date(
+        Date.now() + ttlHours * 60 * 60 * 1e3
+      ).toISOString();
+      await config.client.from(tableName).upsert(
+        {
+          schema_id: draft.schemaId,
+          session_token: draft.sessionToken,
+          partial_data: draft.partialData,
+          current_section_id: draft.currentSectionId,
+          visited_section_ids: draft.visitedSectionIds,
+          expires_at: expiresAt,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        { onConflict: "schema_id,session_token" }
+      );
+    },
+    async load(schemaId, sessionToken) {
+      const { data, error } = await config.client.from(tableName).select("*").eq("schema_id", schemaId).eq("session_token", sessionToken).gt("expires_at", (/* @__PURE__ */ new Date()).toISOString()).single();
+      if (error || !data) return null;
+      return {
+        schemaId: data.schema_id,
+        sessionToken: data.session_token,
+        partialData: data.partial_data,
+        currentSectionId: data.current_section_id,
+        visitedSectionIds: data.visited_section_ids,
+        savedAt: data.updated_at,
+        expiresAt: data.expires_at
+      };
+    },
+    async delete(schemaId, sessionToken) {
+      await config.client.from(tableName).delete().eq("schema_id", schemaId).eq("session_token", sessionToken);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSupabaseAdapter,
+  createSupabaseDraftAdapter,
+  decryptFields,
+  encryptFields
+});

package/dist/index.mjs

@@ -0,0 +1,135 @@
+// src/encryption.ts
+import crypto from "crypto";
+var IV_LENGTH = 12;
+var AUTH_TAG_LENGTH = 16;
+function parseKey(keyBase64) {
+  const key = Buffer.from(keyBase64, "base64");
+  if (key.length !== 32) {
+    throw new Error("Encryption key must be exactly 32 bytes (base64-encoded)");
+  }
+  return key;
+}
+function encryptValue(plaintext, key) {
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final()
+  ]);
+  const authTag = cipher.getAuthTag();
+  return Buffer.concat([iv, encrypted, authTag]).toString("base64");
+}
+function decryptValue(encoded, key) {
+  const buf = Buffer.from(encoded, "base64");
+  const iv = buf.subarray(0, IV_LENGTH);
+  const authTag = buf.subarray(buf.length - AUTH_TAG_LENGTH);
+  const ciphertext = buf.subarray(IV_LENGTH, buf.length - AUTH_TAG_LENGTH);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+  return decipher.update(ciphertext) + decipher.final("utf8");
+}
+function encryptFields(values, fieldIds, keyBase64) {
+  const key = parseKey(keyBase64);
+  const result = { ...values };
+  for (const fieldId of fieldIds) {
+    if (result[fieldId] !== void 0 && result[fieldId] !== null) {
+      result[fieldId] = encryptValue(
+        JSON.stringify(result[fieldId]),
+        key
+      );
+    }
+  }
+  return result;
+}
+function decryptFields(values, fieldIds, keyBase64) {
+  const key = parseKey(keyBase64);
+  const result = { ...values };
+  for (const fieldId of fieldIds) {
+    if (typeof result[fieldId] === "string") {
+      result[fieldId] = JSON.parse(
+        decryptValue(result[fieldId], key)
+      );
+    }
+  }
+  return result;
+}
+
+// src/supabase-adapter.ts
+function createSupabaseAdapter(config) {
+  return {
+    name: "supabase",
+    async submit(response) {
+      let values = { ...response.values };
+      if (config.encryptFields?.length && config.encryptionKey) {
+        values = encryptFields(
+          values,
+          config.encryptFields,
+          config.encryptionKey
+        );
+      }
+      const { error } = await config.client.from(config.table ?? "formengine_responses").insert({
+        schema_id: response.schemaId,
+        schema_version: response.schemaVersion,
+        session_token: response.sessionToken,
+        data: values,
+        metadata: response.metadata,
+        completion_time_ms: response.completionTimeMs,
+        submitted_at: response.submittedAt
+      });
+      if (error) {
+        const err = new Error(`Supabase insert failed: ${error.message}`);
+        config.onError?.(err);
+        throw err;
+      }
+      config.onSuccess?.(response, values);
+    },
+    onError: config.onError
+  };
+}
+
+// src/supabase-draft-adapter.ts
+function createSupabaseDraftAdapter(config) {
+  const tableName = config.table ?? "formengine_drafts";
+  const ttlHours = config.ttlHours ?? 72;
+  return {
+    async save(draft) {
+      const expiresAt = new Date(
+        Date.now() + ttlHours * 60 * 60 * 1e3
+      ).toISOString();
+      await config.client.from(tableName).upsert(
+        {
+          schema_id: draft.schemaId,
+          session_token: draft.sessionToken,
+          partial_data: draft.partialData,
+          current_section_id: draft.currentSectionId,
+          visited_section_ids: draft.visitedSectionIds,
+          expires_at: expiresAt,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        { onConflict: "schema_id,session_token" }
+      );
+    },
+    async load(schemaId, sessionToken) {
+      const { data, error } = await config.client.from(tableName).select("*").eq("schema_id", schemaId).eq("session_token", sessionToken).gt("expires_at", (/* @__PURE__ */ new Date()).toISOString()).single();
+      if (error || !data) return null;
+      return {
+        schemaId: data.schema_id,
+        sessionToken: data.session_token,
+        partialData: data.partial_data,
+        currentSectionId: data.current_section_id,
+        visitedSectionIds: data.visited_section_ids,
+        savedAt: data.updated_at,
+        expiresAt: data.expires_at
+      };
+    },
+    async delete(schemaId, sessionToken) {
+      await config.client.from(tableName).delete().eq("schema_id", schemaId).eq("session_token", sessionToken);
+    }
+  };
+}
+export {
+  createSupabaseAdapter,
+  createSupabaseDraftAdapter,
+  decryptFields,
+  encryptFields
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@squaredr/fieldcraft-supabase",
+  "version": "1.0.0",
+  "description": "FieldCraft Supabase storage adapter with field-level AES-256-GCM encryption",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@squaredr/fieldcraft-core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": "^2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.5",
+    "tsup": "^8.0",
+    "vitest": "^2.0"
+  },
+  "license": "MIT",
+  "author": "SquaredR",
+  "homepage": "https://squaredr.tech/products/fieldcraft",
+  "bugs": {
+    "url": "https://github.com/SquaredR98/fieldcraft/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SquaredR98/fieldcraft.git",
+    "directory": "packages/adapters/supabase"
+  },
+  "keywords": ["fieldcraft", "form-engine", "supabase", "adapter", "storage", "encryption"],
+  "engines": {
+    "node": ">=18"
+  }
+}