@isomorph.ai/app-sdk 1.2.1

package/dist/supabase-compat.js

@@ -0,0 +1,308 @@
+/**
+ * supabase-js compatibility layer for the Isomorph App SDK.
+ *
+ * Converted Supabase apps swap `createClient` from '@supabase/supabase-js' for
+ * `createSupabaseCompatClient(createClient())` and keep call sites unchanged.
+ * Everything here maps onto the existing Isomorph client surfaces only; nothing
+ * new is invented on the wire.
+ *
+ * Contract differences this bridges (all found in converted-app reviews):
+ * - supabase call sites destructure `{ data, error }` and expect NEVER to see a
+ *   throw; the Isomorph SDK returns values and throws IsomorphError. Every async
+ *   method here catches and returns a PostgrestError-shaped `error` instead.
+ * - `functions.invoke(name, { body })` must UNWRAP the `body` option before it
+ *   reaches the action server (supabase-js does; a passthrough left payloads
+ *   wrapped in `{ body: ... }`).
+ * - storage is bucket-scoped in supabase and path-scoped in Isomorph; object
+ *   keys are mapped as `<bucket>/<path>` so distinct buckets stay distinct.
+ */
+import { IsomorphError, } from './index.js';
+/**
+ * Decode a selected result without asserting a relation shape the SDK cannot
+ * infer from a select string. The decoder should check the extra fields and
+ * return the desired shape; a thrown validation error becomes a compat error.
+ * Existing query errors bypass the decoder, and successful counts are retained.
+ */
+export function decodeSupabaseCompatResponse(response, decode) {
+    if (response.error)
+        return response;
+    try {
+        return { data: decode(response.data), error: null, count: response.count };
+    }
+    catch (error) {
+        return { data: null, error: toCompatError(error), count: null };
+    }
+}
+function toCompatError(error) {
+    if (error instanceof IsomorphError) {
+        return { message: error.message, code: error.category, details: error.details };
+    }
+    if (error instanceof Error)
+        return { message: error.message };
+    return { message: String(error) };
+}
+function notSupported(method) {
+    return { message: `not supported on Isomorph: ${method}` };
+}
+export class SupabaseCompatQueryBuilder {
+    inner;
+    head;
+    constructor(inner, ...head) {
+        this.inner = inner;
+        // Omitting the flag is allowed only for the default Head=false builder.
+        this.head = (head[0] ?? false);
+    }
+    chain(next) {
+        return new SupabaseCompatQueryBuilder(next, this.head);
+    }
+    select(columns, options) {
+        return new SupabaseCompatQueryBuilder(this.inner.select(columns, options), options?.head ?? false);
+    }
+    insert(values) {
+        return this.chain(this.inner.insert(values));
+    }
+    update(values) {
+        return this.chain(this.inner.update(values));
+    }
+    /** Optionless `upsert(row)` must pass through untouched (supabase allows it). */
+    upsert(values, options) {
+        return this.chain(this.inner.upsert(values, options));
+    }
+    delete() { return this.chain(this.inner.delete()); }
+    eq(column, value) { return this.chain(this.inner.eq(column, value)); }
+    neq(column, value) { return this.chain(this.inner.neq(column, value)); }
+    gt(column, value) { return this.chain(this.inner.gt(column, value)); }
+    gte(column, value) { return this.chain(this.inner.gte(column, value)); }
+    lt(column, value) { return this.chain(this.inner.lt(column, value)); }
+    lte(column, value) { return this.chain(this.inner.lte(column, value)); }
+    is(column, value) { return this.chain(this.inner.is(column, value)); }
+    not(column, operator, value) {
+        return this.chain(this.inner.not(column, operator, value));
+    }
+    in(column, values) { return this.chain(this.inner.in(column, values)); }
+    ilike(column, value) { return this.chain(this.inner.ilike(column, value)); }
+    or(expression) { return this.chain(this.inner.or(expression)); }
+    order(column, options) {
+        return this.chain(this.inner.order(column, options));
+    }
+    limit(value) { return this.chain(this.inner.limit(value)); }
+    range(from, to) { return this.chain(this.inner.range(from, to)); }
+    single() {
+        return new SupabaseCompatQueryBuilder(this.inner.single(), this.head);
+    }
+    maybeSingle() {
+        return new SupabaseCompatQueryBuilder(this.inner.maybeSingle(), this.head);
+    }
+    async resolve() {
+        try {
+            const result = await this.inner.execute();
+            // Head carries the same flag sent to the gateway. TypeScript cannot
+            // narrow a generic boolean, so record just this conditional here.
+            const data = (this.head ? null : result.data);
+            return { data, error: null, count: result.count ?? null };
+        }
+        catch (error) {
+            return { data: null, error: toCompatError(error), count: null };
+        }
+    }
+    then(onfulfilled, onrejected) {
+        return this.resolve().then(onfulfilled, onrejected);
+    }
+}
+function toCompatUser(user) {
+    const metadata = typeof user.appUser === 'object' && user.appUser !== null
+        ? user.appUser
+        : {};
+    return { id: user.id, email: user.email, app_metadata: {}, user_metadata: metadata };
+}
+function toCompatSession(user) {
+    return { user: toCompatUser(user), access_token: 'isomorph-gateway-cookie', token_type: 'bearer' };
+}
+/** Supabase buckets map to Isomorph path prefixes: object key = `<bucket>/<path>`. */
+function objectPath(bucket, path) {
+    return `${bucket.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+function toBlob(body, contentType) {
+    if (body instanceof Blob)
+        return body;
+    return new Blob([body], { type: contentType ?? 'application/octet-stream' });
+}
+/**
+ * Build a supabase-js-shaped client on top of an existing Isomorph client.
+ * Pass the object returned by the SDK's `createClient`.
+ */
+export function createSupabaseCompatClient(isomorph) {
+    return {
+        from(table) {
+            return new SupabaseCompatQueryBuilder(isomorph.data.from(table));
+        },
+        rpc: async (name, params = {}) => {
+            try {
+                // The gateway returns a scalar function's result as PostgREST-style
+                // rows ([{fn_name: value}]); supabase-js rpc() resolves the bare
+                // value. Unwrap that shape so untouched call sites destructure
+                // correctly (a winner's user.id came back undefined without this).
+                const raw = await isomorph.data.rpc(name, params);
+                let data = raw;
+                if (Array.isArray(raw) && raw.length === 1 && raw[0] !== null && typeof raw[0] === 'object') {
+                    const row = raw[0];
+                    const keys = Object.keys(row);
+                    if (keys.length === 1 && keys[0] === name) {
+                        data = row[name];
+                    }
+                }
+                return { data: data, error: null };
+            }
+            catch (error) {
+                return { data: null, error: toCompatError(error) };
+            }
+        },
+        auth: {
+            getSession: async () => {
+                try {
+                    const user = await isomorph.identity.current();
+                    return { data: { session: user ? toCompatSession(user) : null }, error: null };
+                }
+                catch (error) {
+                    return { data: { session: null }, error: toCompatError(error) };
+                }
+            },
+            getUser: async () => {
+                try {
+                    const user = await isomorph.identity.current();
+                    // Signed-out is data.user = null with error = null (kinder than
+                    // supabase's AuthSessionMissingError for `if (user)` call sites).
+                    return { data: { user: user ? toCompatUser(user) : null }, error: null };
+                }
+                catch (error) {
+                    return { data: { user: null }, error: toCompatError(error) };
+                }
+            },
+            onAuthStateChange: (callback) => {
+                const unsubscribe = isomorph.identity.onChange((user) => {
+                    if (user)
+                        callback('SIGNED_IN', toCompatSession(user));
+                    else
+                        callback('SIGNED_OUT', null);
+                });
+                return { data: { subscription: { unsubscribe } } };
+            },
+            /**
+             * The Isomorph edge gateway owns sign-out: this clears local identity and
+             * redirects the browser through /__harbour/logout (via identity.signOut).
+             */
+            signOut: async () => {
+                isomorph.identity.signOut();
+                return { error: null };
+            },
+        },
+        functions: {
+            invoke: async (name, options) => {
+                try {
+                    if (options?.method !== undefined && options.method !== 'POST') {
+                        return { data: null, error: notSupported(`functions.invoke method ${options.method}`) };
+                    }
+                    if (options?.headers && Object.keys(options.headers).length > 0) {
+                        return { data: null, error: notSupported('functions.invoke custom headers') };
+                    }
+                    // supabase-js unwraps the `body` option before sending; a converted
+                    // app's action server must receive the payload, not `{ body: ... }`.
+                    return { data: await isomorph.actions.invoke(name, options?.body ?? {}), error: null };
+                }
+                catch (error) {
+                    return { data: null, error: toCompatError(error) };
+                }
+            },
+        },
+        storage: {
+            from: (bucket) => ({
+                upload: async (path, body, options) => {
+                    try {
+                        const fullPath = objectPath(bucket, path);
+                        await isomorph.files.upload(fullPath, toBlob(body, options?.contentType));
+                        return { data: { path, fullPath }, error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                /** Mapped through createSignedUrl + a plain fetch of the signed URL. */
+                download: async (path) => {
+                    try {
+                        const { signedUrl } = await isomorph.files.createSignedUrl(objectPath(bucket, path));
+                        const response = await globalThis.fetch(signedUrl);
+                        if (!response.ok) {
+                            return { data: null, error: { message: `download failed with ${response.status}` } };
+                        }
+                        return { data: await response.blob(), error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                remove: async (paths) => {
+                    try {
+                        await isomorph.files.remove(paths.map((path) => objectPath(bucket, path)));
+                        return { data: paths.map((name) => ({ name })), error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                list: async (prefix = '') => {
+                    try {
+                        return { data: await isomorph.files.list(objectPath(bucket, prefix)), error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                /** Sync, like supabase-js: URL construction only, no network call. */
+                getPublicUrl: (path) => ({
+                    data: { publicUrl: isomorph.files.getPublicUrl(objectPath(bucket, path)) },
+                }),
+                createSignedUrl: async (path, expiresIn) => {
+                    try {
+                        const { signedUrl } = await isomorph.files.createSignedUrl(objectPath(bucket, path), expiresIn);
+                        return { data: { signedUrl }, error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                createSignedUrls: async (paths, expiresIn) => {
+                    try {
+                        const signed = await isomorph.files.createSignedUrls(paths.map((path) => objectPath(bucket, path)), expiresIn);
+                        return { data: signed, error: null };
+                    }
+                    catch (error) {
+                        return { data: null, error: toCompatError(error) };
+                    }
+                },
+                /** No Isomorph files move; declared so call sites fail loudly, not with a TypeError. */
+                move: async (fromPath, toPath) => {
+                    void fromPath;
+                    void toPath;
+                    return { data: null, error: notSupported('storage.move') };
+                },
+                /** No Isomorph files copy; declared so call sites fail loudly, not with a TypeError. */
+                copy: async (fromPath, toPath) => {
+                    void fromPath;
+                    void toPath;
+                    return { data: null, error: notSupported('storage.copy') };
+                },
+            }),
+        },
+        /** Isomorph's channel builder is already supabase-shaped; pure passthrough. */
+        channel: (name) => isomorph.realtime.channel(name),
+        removeChannel: (subscription) => {
+            try {
+                subscription.unsubscribe();
+                return Promise.resolve('ok');
+            }
+            catch {
+                return Promise.resolve('error');
+            }
+        },
+    };
+}

package/dist/supabase-compat.typecheck.d.ts

@@ -0,0 +1,23 @@
+declare function typedRows(): Promise<string | null>;
+declare function untypedDefault(): Promise<unknown>;
+declare function singleAfterErrorGuard(): Promise<string>;
+declare function maybeSingleStillAllowsNoRow(): Promise<string | undefined>;
+declare function headCount(options?: {
+    count?: 'exact';
+    head?: boolean;
+}): Promise<number | null>;
+type LineTable = 'cost_sheet_materials' | 'cost_sheet_labour' | 'cost_sheet_overhead';
+declare function knownTableUnion(table: LineTable): Promise<string | undefined>;
+declare function unknownTableRemainsPermissive(table: string): Promise<unknown>;
+declare function checkedNestedSelection(): Promise<string | null>;
+export declare const _compatTypingChecks: {
+    typedRows: typeof typedRows;
+    untypedDefault: typeof untypedDefault;
+    singleAfterErrorGuard: typeof singleAfterErrorGuard;
+    maybeSingleStillAllowsNoRow: typeof maybeSingleStillAllowsNoRow;
+    headCount: typeof headCount;
+    knownTableUnion: typeof knownTableUnion;
+    unknownTableRemainsPermissive: typeof unknownTableRemainsPermissive;
+    checkedNestedSelection: typeof checkedNestedSelection;
+};
+export {};

package/dist/supabase-compat.typecheck.js

@@ -0,0 +1,92 @@
+// Compile-time assertions for the compat client's Database typing. This file
+// ships no runtime code; `tsc -p` (npm test) is what checks it.
+import { createSupabaseCompatClient, decodeSupabaseCompatResponse } from './index.js';
+async function typedRows() {
+    const supabase = createSupabaseCompatClient(source);
+    const { data } = await supabase.from('approval_steps').select('*');
+    const step = data?.[0];
+    // approver_email is a typed column, not unknown.
+    return step ? step.approver_email : null;
+}
+async function untypedDefault() {
+    const supabase = createSupabaseCompatClient(source);
+    const { data } = await supabase.from('anything').select('*');
+    // Without a Database type every row stays Record<string, unknown>.
+    const value = data?.[0]?.whatever;
+    return value;
+}
+async function singleAfterErrorGuard() {
+    const supabase = createSupabaseCompatClient(source);
+    const { data, error } = await supabase.from('approval_steps').insert({}).select().single();
+    if (error)
+        throw error;
+    return data.id;
+}
+async function maybeSingleStillAllowsNoRow() {
+    const supabase = createSupabaseCompatClient(source);
+    const { data, error } = await supabase.from('approval_steps').select().maybeSingle();
+    if (error)
+        throw error;
+    // @ts-expect-error maybeSingle can succeed without a row.
+    const required = data;
+    return data?.id;
+}
+async function headCount(options) {
+    const supabase = createSupabaseCompatClient(source);
+    const { data, error, count } = await supabase.from('approval_steps').select('id', { head: true, count: 'exact' }).eq('id', '1');
+    if (error)
+        throw error;
+    const empty = data;
+    const dynamic = await supabase.from('approval_steps').select('id', options);
+    if (!dynamic.error) {
+        // @ts-expect-error a dynamic head option can produce null on success.
+        const rows = dynamic.data;
+    }
+    const selected = await supabase.from('approval_steps').select('id', { head: true }).select('*');
+    if (!selected.error) {
+        const rows = selected.data;
+    }
+    return count;
+}
+async function knownTableUnion(table) {
+    const supabase = createSupabaseCompatClient(source);
+    const { data, error } = await supabase.from(table).select('*');
+    if (error)
+        throw error;
+    return data[0]?.id;
+}
+async function unknownTableRemainsPermissive(table) {
+    const supabase = createSupabaseCompatClient(source);
+    const { data } = await supabase.from(table).select('*');
+    const value = data?.[0]?.id;
+    // @ts-expect-error an unknown table cannot promise a typed id.
+    const id = value;
+    return value;
+}
+function contactWithProject(row) {
+    if (!('projects' in row))
+        throw new Error('contacts selection omitted projects');
+    const project = row.projects;
+    if (project === null)
+        return { ...row, projects: null };
+    if (typeof project !== 'object' || !('name' in project) || typeof project.name !== 'string') {
+        throw new Error('invalid selected project');
+    }
+    return { ...row, projects: { name: project.name } };
+}
+async function checkedNestedSelection() {
+    const supabase = createSupabaseCompatClient(source);
+    const response = decodeSupabaseCompatResponse(await supabase.from('contacts').select('*, projects(name)'), rows => rows.map(contactWithProject));
+    const { data, error } = response;
+    if (error)
+        throw error;
+    const row = data[0];
+    if (!row)
+        return null;
+    const originalColumn = row.project_id;
+    return row.projects?.name ?? originalColumn;
+}
+export const _compatTypingChecks = {
+    typedRows, untypedDefault, singleAfterErrorGuard, maybeSingleStillAllowsNoRow,
+    headCount, knownTableUnion, unknownTableRemainsPermissive, checkedNestedSelection,
+};

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@isomorph.ai/app-sdk",
+  "version": "1.2.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "5.9.2"
+  }
+}