@svadmin/supabase 0.13.9 → 0.15.1

package/src/data-provider.ts

@@ -1,207 +1,141 @@
-import type { CustomParams, CustomResult, DataProvider } from '@svadmin/core';
+import { definedOptions } from '@svadmin/core/options';
+import { decodeCustomResult, rejectProviderResponse, type DataTransport } from '@svadmin/core/schema';
+import type { DataProvider, Filter } from '@svadmin/core';
 import { createRefineAdapter } from '@svadmin/refine-adapter';
-import type { SupabaseClient } from '@supabase/supabase-js';
-// Static import — dynamic import() gets dropped by Vite/Rollup in static SPA builds
+import { isObject, inputObject, inputRecord, optionalString, optionalBoolean, optionalCount, callSdk, sdkData, executeSupabaseRpc } from './sdk-boundary';
+// Static import keeps the provider available in bundled SPA builds.
 import { dataProvider as refineDataProvider } from '@refinedev/supabase';
 
 export interface CreateSupabaseDataProviderOptions {
-  /** Default schema for table and RPC operations */
+  /** Default schema for table and RPC operations. */
   schema?: string;
 }
 
-/**
- * Creates a supabase data provider using the official @refinedev/supabase package
- * with full support for custom RPC calls, Edge Functions, and schema targeting.
- *
- * @param client SupabaseClient instance
- * @param options Optional provider configuration
- * @returns A fully compatible svadmin DataProvider with custom RPC support
- */
-export function createSupabaseDataProvider(
-  client: SupabaseClient,
-  options: CreateSupabaseDataProviderOptions = {}
-): DataProvider {
-  if (typeof refineDataProvider !== 'function') {
-    throw new Error(
-      '[svadmin/supabase] Failed to resolve @refinedev/supabase data provider. ' +
-      'Ensure the package is installed correctly: bun add @refinedev/supabase'
-    );
-  }
+function edgeBody(value: unknown): unknown {
+  if (value === undefined || typeof value === 'string') return value;
+  if (typeof Blob !== 'undefined' && value instanceof Blob) return value;
+  if (value instanceof ArrayBuffer) return value;
+  if (typeof FormData !== 'undefined' && value instanceof FormData) return value;
+  return inputRecord(value, 'Supabase Edge Function body');
+}
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const refineProvider = refineDataProvider(client as any);
-  const adapter = createRefineAdapter(refineProvider);
+function applyEqualityQuery(builder: unknown, query: Record<string, unknown> | undefined): unknown {
+  let result = builder;
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined) result = callSdk(result, 'eq', [key, value]);
+  }
+  return result;
+}
 
-  // Provide first-class custom implementation for Supabase
-  adapter.custom = async <TData = unknown, TVariables = unknown>({
-    url,
-    method = 'get',
-    payload,
-    query,
-    headers,
-    filters,
-    sorters,
-    meta,
-  }: CustomParams<TVariables>): Promise<CustomResult<TData>> => {
-    const targetSchema = (meta?.schema as string | undefined) ?? options.schema;
-    const targetClient = targetSchema ? client.schema(targetSchema) : client;
+function validateFilters(filters: readonly Filter[] | undefined): void {
+  for (const filter of filters ?? []) {
+    if (!('field' in filter) || filter.operator !== 'eq') {
+      throw new TypeError('Supabase custom table requests support only equality filters');
+    }
+    if (filter.value === null || filter.value === undefined) throw new TypeError('Supabase equality filters require a non-null value');
+  }
+}
 
-    // 1. Edge Function invocation
-    const isEdgeFunction =
-      meta?.function === true ||
-      meta?.edgeFunction === true ||
-      url.startsWith('functions/') ||
-      url.startsWith('functions:');
+function applyFilters(builder: unknown, filters: readonly Filter[] | undefined): unknown {
+  let result = builder;
+  for (const filter of filters ?? []) {
+    if ('field' in filter) result = callSdk(result, 'eq', [filter.field, filter.value]);
+  }
+  return result;
+}
 
-    if (isEdgeFunction) {
-      const functionName = url.replace(/^functions[/:]/, '');
-      const { data, error } = await client.functions.invoke(functionName, {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        body: payload as any,
-        headers: headers as Record<string, string>,
-      });
+async function parseHttpResponse(response: Response): Promise<unknown> {
+  if (response.status === 204 || response.status === 205 || response.headers.get('content-length')?.trim() === '0') return undefined;
+  const body = await response.text();
+  return body.trim() ? JSON.parse(body) : undefined;
+}
 
-      if (error) {
-        throw new Error(
-          `[svadmin/supabase] Edge Function "${functionName}" failed: ${error.message}`
-        );
-      }
+/**
+ * Adapts a Supabase SDK instance without assuming its dynamic response types.
+ * Resource/command contracts provide the business schema above this transport.
+ */
+export function createSupabaseDataProvider(
+  client: unknown,
+  options: CreateSupabaseDataProviderOptions = {},
+): DataProvider {
+  inputObject(client, 'Supabase client');
+  const defaultSchema = optionalString(options, 'schema');
+  if (typeof refineDataProvider !== 'function') throw new Error('[svadmin/supabase] Missing @refinedev/supabase data provider');
+  const adapter = createRefineAdapter(refineDataProvider(client));
+
+  const executeCustom: NonNullable<DataTransport['custom']> = async ({
+    url, method, payload, query, headers, filters, sorters, meta,
+  }) => {
+    if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) throw new TypeError('Unsupported Supabase request method');
+    const targetSchema = optionalString(meta, 'schema') ?? defaultSchema;
+    const select = optionalString(meta, 'select') ?? '*';
+    const rpc = optionalBoolean(meta, 'rpc');
+    const edge = optionalBoolean(meta, 'function');
+    const edgeFunction = optionalBoolean(meta, 'edgeFunction');
+    const rpcOptions = definedOptions({
+      head: optionalBoolean(meta, 'head'), get: optionalBoolean(meta, 'get') ?? method === 'get', count: optionalCount(meta),
+    });
+    const write = method !== 'get';
 
-      return { data: data as TData };
+    if (edge || edgeFunction || url.startsWith('functions/') || url.startsWith('functions:')) {
+      const functionName = url.replace(/^functions[/:]/, '');
+      if (!functionName.trim()) throw new TypeError('Supabase function name cannot be empty');
+      const source = inputObject(client, 'Supabase client');
+      const body = edgeBody(payload);
+      if (method === 'get' && body !== undefined) throw new TypeError('A GET function request cannot have a body');
+      const invocation = callSdk(source['functions'], 'invoke', [functionName, definedOptions({
+        body,
+        headers,
+        method: method.toUpperCase(),
+      })]);
+      return { data: await sdkData(invocation, `Edge Function "${functionName}"`, write) };
     }
 
-    // 2. PostgreSQL Stored Procedure / RPC
-    const isExplicitRpc =
-      meta?.rpc === true ||
-      url.startsWith('rpc/') ||
-      url.startsWith('rpc:');
-    const isImplicitRpc =
-      !isExplicitRpc &&
-      meta?.rpc !== false &&
-      !url.startsWith('http://') &&
-      !url.startsWith('https://') &&
-      !url.includes('/') &&
-      (method === 'post' || meta?.rpc === true);
-
-    if (isExplicitRpc || (isImplicitRpc && meta?.rpc === true)) {
+    if (rpc === true || url.startsWith('rpc/') || url.startsWith('rpc:')) {
       const functionName = url.replace(/^rpc[/:]/, '');
-      const rpcArgs = (payload ?? query ?? {}) as Record<string, unknown>;
-      const rpcOptions: { head?: boolean; count?: 'exact' | 'planned' | 'estimated'; get?: boolean } = {};
-      if (meta?.head) rpcOptions.head = Boolean(meta.head);
-      if (meta?.count) rpcOptions.count = meta.count as 'exact' | 'planned' | 'estimated';
-      if (meta?.get) rpcOptions.get = Boolean(meta.get);
-
-      const { data, error } = await targetClient.rpc(functionName, rpcArgs, rpcOptions);
-
-      if (error) {
-        throw new Error(
-          `[svadmin/supabase] RPC function "${functionName}" failed: ${error.message}`
-        );
-      }
-
-      return { data: data as TData };
+      if (!functionName.trim()) throw new TypeError('Supabase RPC name cannot be empty');
+      const args = payload === undefined ? query ?? {} : payload;
+      return { data: await executeSupabaseRpc(client, functionName, args, definedOptions({ schema: targetSchema, ...rpcOptions })) };
     }
 
-    // 3. Direct Table / View Query via PostgREST client
     if (!url.startsWith('http://') && !url.startsWith('https://')) {
-      const dbQuery = targetClient.from(url);
-
-      if (method === 'get') {
-        let selectQuery = dbQuery.select((meta?.select as string) ?? '*');
-        if (query) {
-          for (const [key, value] of Object.entries(query)) {
-            if (value !== undefined && value !== null) {
-              selectQuery = selectQuery.eq(key, value);
-            }
-          }
-        }
-        if (filters && Array.isArray(filters)) {
-          for (const filter of filters) {
-            if ('field' in filter && 'value' in filter) {
-              selectQuery = selectQuery.eq(filter.field, filter.value);
-            }
-          }
-        }
-        if (sorters && Array.isArray(sorters)) {
-          for (const sorter of sorters) {
-            selectQuery = selectQuery.order(sorter.field, {
-              ascending: sorter.order === 'asc',
-            });
-          }
-        }
-        const { data, error } = await selectQuery;
-        if (error) {
-          throw new Error(`[svadmin/supabase] Query "${url}" failed: ${error.message}`);
-        }
-        return { data: data as TData };
+      validateFilters(filters);
+      if (Object.values(query ?? {}).some(value => value === null)) {
+        throw new TypeError('Supabase equality queries require non-null values');
       }
-
-      if (method === 'post') {
-        const { data, error } = await dbQuery
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          .insert(payload as any)
-          .select((meta?.select as string) ?? '*');
-        if (error) {
-          throw new Error(`[svadmin/supabase] Insert into "${url}" failed: ${error.message}`);
-        }
-        return { data: (Array.isArray(data) ? data[0] : data) as TData };
-      }
-
-      if (method === 'put' || method === 'patch') {
-        let updateQuery = dbQuery
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          .update(payload as any);
-        if (query) {
-          for (const [key, value] of Object.entries(query)) {
-            if (value !== undefined && value !== null) {
-              updateQuery = updateQuery.eq(key, value);
-            }
-          }
-        }
-        const { data, error } = await updateQuery.select((meta?.select as string) ?? '*');
-        if (error) {
-          throw new Error(`[svadmin/supabase] Update "${url}" failed: ${error.message}`);
-        }
-        return { data: (Array.isArray(data) ? data[0] : data) as TData };
+      const variables = method === 'post' || method === 'put' || method === 'patch'
+        ? inputRecord(payload, 'Supabase table variables') : undefined;
+      const target = targetSchema ? callSdk(client, 'schema', [targetSchema]) : client;
+      const table = callSdk(target, 'from', [url]);
+      let builder: unknown;
+      if (method === 'get') builder = callSdk(table, 'select', [select]);
+      else if (method === 'post') builder = callSdk(table, 'insert', [variables]);
+      else if (method === 'put' || method === 'patch') builder = callSdk(table, 'update', [variables]);
+      else builder = callSdk(table, 'delete', []);
+      builder = applyFilters(applyEqualityQuery(builder, query), filters);
+      if (method === 'get') {
+        for (const sorter of sorters ?? []) builder = callSdk(builder, 'order', [sorter.field, { ascending: sorter.order === 'asc' }]);
+      } else {
+        builder = callSdk(builder, 'select', [select]);
       }
-
-      if (method === 'delete') {
-        let deleteQuery = dbQuery.delete();
-        if (query) {
-          for (const [key, value] of Object.entries(query)) {
-            if (value !== undefined && value !== null) {
-              deleteQuery = deleteQuery.eq(key, value);
-            }
-          }
-        }
-        const { data, error } = await deleteQuery.select((meta?.select as string) ?? '*');
-        if (error) {
-          throw new Error(`[svadmin/supabase] Delete from "${url}" failed: ${error.message}`);
-        }
-        return { data: data as TData };
+      const data = await sdkData(builder, `Table request "${url}"`, write);
+      if (method === 'post' || method === 'put' || method === 'patch') {
+        if (!Array.isArray(data) || data.length !== 1 || !isObject(data[0])) return rejectProviderResponse(write);
+        return { data: data[0] };
       }
+      if (!Array.isArray(data) || !data.every(isObject)) return rejectProviderResponse(write);
+      return { data };
     }
 
-    // 4. Fallback to standard HTTP fetch for absolute URLs
-    const fetchHeaders: Record<string, string> = {
-      'Content-Type': 'application/json',
-      ...(headers ?? {}),
-    };
-    const response = await fetch(url, {
+    const response = await fetch(url, definedOptions({
       method: method.toUpperCase(),
-      headers: fetchHeaders,
-      body: payload ? JSON.stringify(payload) : undefined,
-    });
-
-    if (!response.ok) {
-      throw new Error(
-        `[svadmin/supabase] Custom request to "${url}" failed with status ${response.status}`
-      );
-    }
-
-    const data = await response.json();
-    return { data: data as TData };
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: payload === undefined ? undefined : JSON.stringify(payload),
+    }));
+    if (!response.ok) throw new Error(`[svadmin/supabase] Custom request failed with status ${response.status}`);
+    return { data: await parseHttpResponse(response) };
   };
 
+  adapter.custom = async params => decodeCustomResult(await executeCustom(params), params.method !== 'get');
   return adapter;
 }

package/src/index.ts

@@ -3,13 +3,23 @@
 export { createSupabaseDataProvider } from './data-provider';
 export type { CreateSupabaseDataProviderOptions } from './data-provider';
 export { createSupabaseAuthProvider } from './auth-provider';
+export {
+  createSupabasePermissionAccessControlProvider,
+  registerSupabasePermissionAccessControl,
+} from './permission-adapter';
+export type { SupabasePermissionSnapshot, SupabasePermissionAdapterOptions } from './permission-adapter';
 export type {
   SupabaseAuthProviderOptions,
+  SupabaseAuthClient,
   SupabasePermissionResolver,
   SupabasePermissionResolverContext,
 } from './auth-provider';
-export { createSupabaseLiveProvider } from './live-provider';
-export { createSupabaseAuditHandler } from './audit-handler';
+export { SupabaseAuthError } from './auth-contract';
+export type { SupabaseAuthUser } from './auth-contract';
+export { createSupabaseLiveProvider, SupabaseLiveError } from './live-provider';
+export type { SupabaseRealtimeChannel, SupabaseRealtimeClient, SupabaseLiveOptions } from './live-provider';
+export { createSupabaseAuditHandler, SupabaseAuditError } from './audit-handler';
+export type { SupabaseAuditClient, SupabaseAuditRow } from './audit-handler';
 export { createSupabaseRpc } from './rpc';
 export type {
   SupabaseRpcClient,
@@ -21,17 +31,12 @@ export {
 } from './supacloud';
 export type {
   SupaCloudTaskClient,
-  SupaCloudTaskLegacyClient,
-  SupaCloudTaskSdkClient,
   SupaCloudTaskRecord,
-  SupaCloudSdkTaskRecord,
-  SupaCloudSdkTaskSubmitOptions,
-  SupaCloudTaskReceipt,
-  SupaCloudTaskSnapshot,
-  SupaCloudTaskSubscribeState,
+  SupaCloudTaskHandle,
+  SupaCloudTaskProvider,
+  SupaCloudTaskListParams,
+  SupaCloudTaskDlqParams,
   SupaCloudTaskSubscribeOptions,
-  SupaCloudSdkTaskWaitOptions,
-  SupaCloudSdkTaskClient,
   CreateSupaCloudTaskProviderOptions,
   CreateSupaCloudTaskLiveProviderOptions,
 } from './supacloud';

package/src/live-provider.ts

@@ -1,90 +1,208 @@
-// Supabase LiveProvider — Real-time subscriptions via Supabase Realtime
-import type { SupabaseClient, RealtimeChannel } from '@supabase/supabase-js';
-import type { LiveProvider, LiveEvent } from '@svadmin/core';
-
-export function createSupabaseLiveProvider(client: SupabaseClient): LiveProvider {
-  const subscribers = new Map<string, Set<(event: LiveEvent) => void>>();
-  const channels = new Map<string, RealtimeChannel>();
-  const broadcastChannels = new Map<string, RealtimeChannel>();
-
-  function getOrCreateChannel(resource: string): RealtimeChannel {
-    let channel = channels.get(resource);
-    if (!channel) {
-      channel = client.channel(`live-${resource}`)
-        .on(
-          'postgres_changes',
-          { event: '*', schema: 'public', table: resource },
-          (payload) => {
-            const event: LiveEvent = {
-              type: payload.eventType as LiveEvent['type'],
-              resource,
-              payload: (payload.new ?? payload.old ?? {}) as Record<string, unknown>,
-            };
-            subscribers.get(resource)?.forEach(cb => cb(event));
-          }
-        )
-        .on('broadcast', { event: 'live-event' }, ({ payload }) => {
-          if (payload) {
-            subscribers.get(resource)?.forEach(cb => cb(payload as LiveEvent));
-          }
-        })
-        .subscribe();
-      channels.set(resource, channel);
+import { Type, type Static, type TSchema } from '@sinclair/typebox';
+import { checkExact, snapshotPlainData } from '@svadmin/core/schema';
+import type { LiveEvent, LiveProvider } from '@svadmin/core';
+
+export interface SupabaseRealtimeChannel {
+  on(type: 'postgres_changes', filter: { event: '*'; schema: 'public'; table: string }, callback: (payload: unknown) => void): unknown;
+  on(type: 'broadcast', filter: { event: 'live-event' }, callback: (payload: unknown) => void): unknown;
+  subscribe(callback: (status: unknown) => void): unknown;
+  send(message: { type: 'broadcast'; event: 'live-event'; payload: LiveEvent }): Promise<unknown>;
+}
+
+export interface SupabaseRealtimeClient<C extends SupabaseRealtimeChannel> {
+  channel(name: string, options: { config: { broadcast: { ack: true } } }): C;
+  removeChannel(channel: C): Promise<unknown>;
+}
+
+type LiveErrorCode = 'INVALID_INPUT' | 'INVALID_EVENT' | 'SUBSCRIBE_FAILED' |
+  'UNSUBSCRIBE_FAILED' | 'PUBLISH_OUTCOME_UNKNOWN' | 'CALLBACK_FAILED';
+
+export class SupabaseLiveError extends Error {
+  constructor(readonly code: LiveErrorCode) {
+    super(`Supabase realtime ${code.toLowerCase().replaceAll('_', ' ')}`);
+    this.name = 'SupabaseLiveError';
+  }
+}
+
+export interface SupabaseLiveOptions {
+  onError?: (error: SupabaseLiveError) => void;
+}
+
+const resourceSchema = Type.String({ minLength: 1, pattern: '^[A-Za-z0-9_]+$' });
+const action = Type.Union([Type.Literal('INSERT'), Type.Literal('UPDATE'), Type.Literal('DELETE')]);
+const record = Type.Record(Type.String(), Type.Unknown());
+const eventSchema = Type.Object({
+  type: action, resource: resourceSchema, payload: record,
+}, { additionalProperties: false });
+const broadcastSchema = Type.Object({
+  type: Type.Literal('broadcast'), event: Type.Literal('live-event'), payload: eventSchema,
+});
+const postgresSchema = Type.Object({
+  schema: Type.Literal('public'), table: resourceSchema, commit_timestamp: Type.String(),
+  eventType: action, new: record, old: record,
+  errors: Type.Union([Type.Null(), Type.Array(Type.String())]),
+});
+
+function decode<S extends TSchema>(schema: S, value: unknown, code: LiveErrorCode): Static<S> {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(schema, candidate)) return candidate;
+  } catch {
+    // SDK callbacks and payload errors must not expose submitted data.
+  }
+  throw new SupabaseLiveError(code);
+}
+
+function postgresEvent(value: unknown, resource: string): LiveEvent {
+  const event = decode(postgresSchema, value, 'INVALID_EVENT');
+  if (event.table !== resource || event.errors?.length) throw new SupabaseLiveError('INVALID_EVENT');
+  const payload = event.eventType === 'DELETE' ? event.old : event.new;
+  if (Object.keys(payload).length === 0) throw new SupabaseLiveError('INVALID_EVENT');
+  return { type: event.eventType, resource, payload };
+}
+
+interface Subscription {
+  callback: (event: LiveEvent) => void;
+}
+
+interface ChannelState<C> {
+  resource: string;
+  listeners: Set<Subscription>;
+  pending: number;
+  retired: boolean;
+  started: boolean;
+  channel?: C;
+  ready: Promise<C | undefined>;
+}
+
+/** All SDK data stays unknown until validated; one channel is owned per resource. */
+export function createSupabaseLiveProvider<C extends SupabaseRealtimeChannel>(
+  client: SupabaseRealtimeClient<C>, options: SupabaseLiveOptions = {},
+): LiveProvider {
+  const channels = new Map<string, ChannelState<C>>();
+  const closing = new Map<string, Promise<void>>();
+  const failedCleanup = new Set<string>();
+  const report = (code: LiveErrorCode): void => {
+    const error = new SupabaseLiveError(code);
+    if (!options.onError) { console.error(error); return; }
+    try {
+      void Promise.resolve(options.onError(error)).catch(() => {
+        console.error('Supabase realtime error handler failed');
+      });
+    }
+    catch { console.error('Supabase realtime error handler failed'); }
+  };
+
+  function release(state: ChannelState<C>, force = false): void {
+    if (state.retired || (!force && (state.listeners.size > 0 || state.pending > 0))) return;
+    state.retired = true;
+    if (channels.get(state.resource) === state) channels.delete(state.resource);
+    const completion = state.ready.then(async () => {
+      if (!state.channel) return;
+      const receipt: unknown = await client.removeChannel(state.channel);
+      if (receipt !== 'ok') throw new SupabaseLiveError('UNSUBSCRIBE_FAILED');
+    }).catch(() => {
+      failedCleanup.add(state.resource);
+      report('UNSUBSCRIBE_FAILED');
+    });
+    closing.set(state.resource, completion);
+    void completion.then(() => {
+      if (closing.get(state.resource) === completion) closing.delete(state.resource);
+    });
+  }
+
+  function deliver(state: ChannelState<C>, value: unknown, kind: 'postgres' | 'broadcast'): void {
+    if (state.retired || state.listeners.size === 0) return;
+    let event: LiveEvent;
+    try {
+      event = kind === 'postgres' ? postgresEvent(value, state.resource)
+        : decode(broadcastSchema, value, 'INVALID_EVENT').payload;
+      if (event.resource !== state.resource) throw new SupabaseLiveError('INVALID_EVENT');
+    } catch {
+      report('INVALID_EVENT');
+      return;
     }
-    return channel;
+    // Each registration owns its lifetime and its copy, even with identical callbacks.
+    for (const subscription of [...state.listeners]) {
+      if (state.retired || !state.listeners.has(subscription)) continue;
+      const copy = decode(eventSchema, event, 'INVALID_EVENT');
+      try {
+        void Promise.resolve(subscription.callback(copy)).catch(() => report('CALLBACK_FAILED'));
+      }
+      catch { report('CALLBACK_FAILED'); }
+    }
+  }
+
+  function getChannel(resource: string): ChannelState<C> {
+    const existing = channels.get(resource);
+    if (existing) return existing;
+    const predecessor = closing.get(resource);
+    const state: ChannelState<C> = {
+      resource, listeners: new Set(), pending: 0, retired: false, started: false,
+      ready: Promise.resolve(undefined),
+    };
+    channels.set(resource, state);
+    state.ready = Promise.resolve(predecessor).then(() => {
+      if (state.retired) return undefined;
+      // An unconfirmed removal may leave the old topic cached in the SDK.
+      if (failedCleanup.has(resource)) throw new SupabaseLiveError('SUBSCRIBE_FAILED');
+      const channel = client.channel(`live-${resource}`, { config: { broadcast: { ack: true } } });
+      state.channel = channel;
+      channel.on('postgres_changes', { event: '*', schema: 'public', table: resource },
+        value => deliver(state, value, 'postgres'));
+      channel.on('broadcast', { event: 'live-event' }, value => deliver(state, value, 'broadcast'));
+      return channel;
+    }).catch(() => {
+      report('SUBSCRIBE_FAILED');
+      release(state, true);
+      return undefined;
+    });
+    return state;
   }
 
-  function getOrCreateBroadcastChannel(resource: string): RealtimeChannel {
-    let channel = broadcastChannels.get(resource);
-    if (!channel) {
-      const existing = channels.get(resource);
-      if (existing) return existing;
-      channel = client.channel(`live-bc-${resource}`)
-        .on('broadcast', { event: 'live-event' }, ({ payload }) => {
-          if (payload) {
-            subscribers.get(resource)?.forEach(cb => cb(payload as LiveEvent));
-          }
-        })
-        .subscribe();
-      broadcastChannels.set(resource, channel);
+  function start(state: ChannelState<C>, channel: C): void {
+    if (state.retired || state.started || state.listeners.size === 0) return;
+    state.started = true;
+    try {
+      channel.subscribe(status => {
+        if (state.retired || status === 'SUBSCRIBED') return;
+        report('SUBSCRIBE_FAILED');
+        // The SDK reconnects these two states. Closed or malformed states are terminal.
+        if (status !== 'CHANNEL_ERROR' && status !== 'TIMED_OUT') release(state, true);
+      });
+    } catch {
+      report('SUBSCRIBE_FAILED');
+      release(state, true);
     }
-    return channel;
   }
 
   return {
     subscribe({ resource, callback }) {
-      if (!subscribers.has(resource)) subscribers.set(resource, new Set());
-      subscribers.get(resource)?.add(callback);
-
-      getOrCreateChannel(resource);
-
+      const name = decode(resourceSchema, resource, 'INVALID_INPUT');
+      const state = getChannel(name);
+      const subscription = { callback };
+      state.listeners.add(subscription);
+      void state.ready.then(channel => { if (channel) start(state, channel); });
+      let cancelled = false;
       return () => {
-        const cbs = subscribers.get(resource);
-        if (cbs) {
-          cbs.delete(callback);
-          if (cbs.size === 0) {
-            subscribers.delete(resource);
-            const channel = channels.get(resource);
-            if (channel) {
-              channel.unsubscribe();
-              channels.delete(resource);
-            }
-            const bc = broadcastChannels.get(resource);
-            if (bc) {
-              bc.unsubscribe();
-              broadcastChannels.delete(resource);
-            }
-          }
-        }
+        if (cancelled) return;
+        cancelled = true;
+        state.listeners.delete(subscription);
+        release(state);
       };
     },
 
-    publish(event: LiveEvent) {
-      const channel = getOrCreateBroadcastChannel(event.resource);
-      channel.send({
-        type: 'broadcast',
-        event: 'live-event',
-        payload: event,
+    publish(value) {
+      const event = decode(eventSchema, value, 'INVALID_INPUT');
+      const state = getChannel(event.resource);
+      state.pending++;
+      void state.ready.then(async channel => {
+        if (!channel || state.retired) throw new SupabaseLiveError('PUBLISH_OUTCOME_UNKNOWN');
+        const receipt: unknown = await channel.send({ type: 'broadcast', event: 'live-event', payload: event });
+        if (receipt !== 'ok') throw new SupabaseLiveError('PUBLISH_OUTCOME_UNKNOWN');
+      }).catch(() => report('PUBLISH_OUTCOME_UNKNOWN')).finally(() => {
+        state.pending--;
+        release(state);
       });
     },
   };