L2 Package Design: @oneplatform/app-sdk¶

// src/index.ts — complete export list
export { AppProvider } from "./provider/AppProvider";
export { useQuery } from "./hooks/useQuery";
export { useMutation } from "./hooks/useMutation";
export { useSubscription } from "./hooks/useSubscription";
export { useUser } from "./hooks/useUser";
export { usePermission } from "./hooks/usePermission";
export { useAppStorage } from "./hooks/useAppStorage";
export type {
  QueryOptions,
  QueryResult,
  MutationResult,
  SubscriptionOptions,
  SubscriptionResult,
  UserContext,
  AppSDKError,
  EntityEvent,
  BulkResult,
  FilterValue,
} from "./types/index";

// ─────────────────────────────────────────────────────────────────────────────
// AppProvider
// ─────────────────────────────────────────────────────────────────────────────

interface AppProviderProps {
  children: React.ReactNode;
  /**
   * Override appId for testing. In production this is always read from
   * window.__OP_APP_CONFIG__.appId and this prop is ignored.
   */
  _testAppId?: string;
  _testTenantId?: string;
}

function AppProvider(props: AppProviderProps): JSX.Element;

// ─────────────────────────────────────────────────────────────────────────────
// useQuery<T>
// ─────────────────────────────────────────────────────────────────────────────

type FilterOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "nin" | "contains";
type FilterValue = string | number | boolean | string[] | number[];

interface FilterSpec {
  [field: string]: Partial<Record<FilterOperator, FilterValue>>;
}

interface QueryOptions {
  filter?: FilterSpec;
  sort?: string[];          // ["name", "-createdAt"] — prefix "-" for DESC
  fields?: string[];        // field projection; omit for all
  cursor?: string;          // pagination cursor; omit for first page
  limit?: number;           // default 50, max 100
  enabled?: boolean;        // if false, skip fetch (default true)
  staleTime?: number;       // ms before refetch on next render (default 30_000)
  onError?: (error: AppSDKError) => void;
}

interface Pagination {
  nextCursor: string | null;
  total: number;
}

interface QueryResult<T> {
  data: T[] | null;
  pagination: Pagination | null;
  isLoading: boolean;
  isError: boolean;
  error: AppSDKError | null;
  refetch: () => Promise<void>;
  fetchNextPage: () => Promise<void>;
}

function useQuery<T = unknown>(
  entity: string,
  options?: QueryOptions
): QueryResult<T>;

// ─────────────────────────────────────────────────────────────────────────────
// useMutation<T>
// ─────────────────────────────────────────────────────────────────────────────

interface BulkResult<T> {
  created: T[];
  errors: Array<{ index: number; error: AppSDKError }>;
}

interface MutationResult<T> {
  create: (data: Partial<T>) => Promise<T>;
  update: (id: string, data: Partial<T>) => Promise<T>;   // PATCH
  replace: (id: string, data: T) => Promise<T>;           // PUT
  remove: (id: string) => Promise<void>;
  bulkCreate: (items: Partial<T>[]) => Promise<BulkResult<T>>;
  isLoading: boolean;
  isError: boolean;
  error: AppSDKError | null;
  reset: () => void;  // clears isError and error
}

function useMutation<T = unknown>(entity: string): MutationResult<T>;

// ─────────────────────────────────────────────────────────────────────────────
// useSubscription<T>
// ─────────────────────────────────────────────────────────────────────────────

type EntityEventType = "created" | "updated" | "deleted";

interface EntityEvent<T> {
  type: EntityEventType;
  entity: string;
  id: string;
  data: T;
  timestamp: string;  // ISO 8601
  tenantId: string;
}

interface SubscriptionOptions {
  filter?: FilterSpec;
  events?: EntityEventType[];  // default: all three
  onEvent?: (event: EntityEvent<unknown>) => void;
}

interface SubscriptionResult<T> {
  lastEvent: EntityEvent<T> | null;
  isConnected: boolean;
  reconnectAttempts: number;
}

function useSubscription<T = unknown>(
  entity: string,
  options?: SubscriptionOptions
): SubscriptionResult<T>;

// ─────────────────────────────────────────────────────────────────────────────
// useUser
// ─────────────────────────────────────────────────────────────────────────────

interface UserContext {
  id: string;
  email: string | null;  // null for guest sessions
  displayName: string;
  tenantId: string;
  roles: string[];
  isGuest: boolean;
}

function useUser(): UserContext;

// ─────────────────────────────────────────────────────────────────────────────
// usePermission
// ─────────────────────────────────────────────────────────────────────────────

type PermissionAction = "create" | "read" | "update" | "delete" | "admin";

function usePermission(
  action: PermissionAction | string,
  resource: string         // entity name or "*" for any
): boolean;

// ─────────────────────────────────────────────────────────────────────────────
// useAppStorage
// ─────────────────────────────────────────────────────────────────────────────

function useAppStorage<T>(
  key: string,
  defaultValue: T
): [T, (value: T) => Promise<void>];

// ─────────────────────────────────────────────────────────────────────────────
// Error type
// ─────────────────────────────────────────────────────────────────────────────

interface AppSDKError {
  code: string;         // e.g. "PERMISSION_DENIED", "ENTITY_NOT_FOUND", "NETWORK_ERROR"
  message: string;
  statusCode: number;   // HTTP status code; 0 for network errors
  isRetryable: boolean; // true for 429, 503, NETWORK_ERROR
  requestId: string;    // X-Request-ID from BFF response; empty string for network errors
}

interface OPAppConfig {
  appId: string;
  tenantId: string;
}

function readAppConfig(overrides?: Partial<OPAppConfig>): OPAppConfig {
  // overrides used only in tests (_testAppId, _testTenantId props)
  const raw = (window as Window & { __OP_APP_CONFIG__?: unknown }).__OP_APP_CONFIG__;
  if (!raw || typeof raw !== "object") {
    throw new Error("[app-sdk] window.__OP_APP_CONFIG__ is missing. Ensure the App Service HTML shell is serving the app correctly.");
  }
  const config = raw as Record<string, unknown>;
  if (typeof config.appId !== "string" || typeof config.tenantId !== "string") {
    throw new Error("[app-sdk] window.__OP_APP_CONFIG__ is missing appId or tenantId.");
  }
  return {
    appId: overrides?.appId ?? config.appId,
    tenantId: overrides?.tenantId ?? config.tenantId,
  };
}

// src/provider/AppContext.ts

interface AppContextValue {
  appId: string;
  tenantId: string;
  bffClient: BffClient;
  permissionCache: PermissionCache;
  wsManager: WebSocketManager;
  user: UserContext | null;      // null while loading
  isReady: boolean;              // true after permissions + user are loaded
}

const AppContext = React.createContext<AppContextValue | null>(null);

export function useAppContext(): AppContextValue {
  const ctx = React.useContext(AppContext);
  if (ctx === null) {
    if (process.env.NODE_ENV !== "production") {
      throw new Error("[app-sdk] Hook called outside of <AppProvider>. Wrap your app root with <AppProvider>.");
    }
    // Production: return a safe no-op context rather than crashing
    return createNullContext();
  }
  return ctx;
}

React.useEffect(() => {
  const onVisible = debounce(() => {
    if (document.visibilityState === "visible") {
      permissionCache.refresh();
    }
  }, 2000);
  document.addEventListener("visibilitychange", onVisible);
  return () => document.removeEventListener("visibilitychange", onVisible);
}, [permissionCache]);

interface AppProviderProps {
  children: React.ReactNode;
  loadingFallback?: React.ReactNode;  // default: null
  _testAppId?: string;
  _testTenantId?: string;
}

// src/client/BffClient.ts

interface BffRequestOptions {
  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
  body?: unknown;
  queryParams?: Record<string, string | number | boolean | string[]>;
  signal?: AbortSignal;
}

class BffClient {
  private readonly baseUrl: string;

  constructor() {
    // Base URL is always the same origin — no configuration needed
    this.baseUrl = window.location.origin;
  }

  async request<T>(path: string, options: BffRequestOptions = {}): Promise<T> {
    const url = new URL(`${this.baseUrl}${path}`);
    if (options.queryParams) {
      appendQueryParams(url.searchParams, options.queryParams);
    }

    let response: Response;
    try {
      response = await fetch(url.toString(), {
        method: options.method ?? "GET",
        headers: {
          "Content-Type": "application/json",
          "Accept": "application/json",
        },
        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
        credentials: "include",  // Always include httpOnly cookie
        redirect: "error",       // Never follow redirects — C-5
        signal: options.signal,
      });
    } catch (err) {
      throw createNetworkError(err);
    }

    if (!response.ok) {
      throw await parseBffError(response);
    }

    return response.json() as Promise<T>;
  }
}

async function parseBffError(response: Response): Promise<AppSDKError> {
  const requestId = response.headers.get("X-Request-ID") ?? "";
  let body: { error?: { code?: string; message?: string } } = {};
  try {
    body = await response.json();
  } catch {
    // non-JSON error body — use HTTP status text
  }
  return {
    code: body.error?.code ?? httpStatusToCode(response.status),
    message: body.error?.message ?? response.statusText,
    statusCode: response.status,
    isRetryable: [429, 503].includes(response.status),
    requestId,
  };
}

function httpStatusToCode(status: number): string {
  const map: Record<number, string> = {
    400: "BAD_REQUEST",
    401: "UNAUTHORIZED",
    403: "PERMISSION_DENIED",
    404: "ENTITY_NOT_FOUND",
    409: "CONFLICT",
    429: "RATE_LIMITED",
    500: "INTERNAL_ERROR",
    503: "SERVICE_UNAVAILABLE",
  };
  return map[status] ?? "UNKNOWN_ERROR";
}

function createNetworkError(err: unknown): AppSDKError {
  const message = err instanceof Error ? err.message : "Network request failed";
  return {
    code: "NETWORK_ERROR",
    message,
    statusCode: 0,
    isRetryable: true,
    requestId: "",
  };
}

// src/cache/PermissionCache.ts

class PermissionCache {
  private snapshot: Map<string, boolean> = new Map();
  private hasWildcardAdmin = false;
  private listeners = new Set<() => void>();
  private refreshTimer: ReturnType<typeof setTimeout> | null = null;
  private readonly REFRESH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes

  async seed(bffClient: BffClient): Promise<void> {
    const data = await bffClient.request<PermissionsResponse>("/bff/permissions");
    this.applySnapshot(data.permissions);
    this.scheduleRefresh(bffClient);
  }

  check(action: string, resource: string): boolean {
    // Admin wildcard on any resource grants all actions on that resource
    if (this.snapshot.get(`admin:*`) === true) return true;
    if (this.snapshot.get(`admin:${resource}`) === true) return true;
    return this.snapshot.get(`${action}:${resource}`) === true ||
           this.snapshot.get(`${action}:*`) === true;
  }

  async refresh(bffClient: BffClient): Promise<void> {
    try {
      const data = await bffClient.request<PermissionsResponse>("/bff/permissions");
      this.applySnapshot(data.permissions);
      this.notifyListeners();
    } catch {
      // Refresh failure is non-fatal. Keep serving the existing snapshot.
      // The next scheduled refresh will try again.
    }
  }

  subscribe(listener: () => void): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }

  private applySnapshot(permissions: PermissionEntry[]): void {
    this.snapshot = new Map(
      permissions.map((p) => [`${p.action}:${p.resource}`, p.allowed])
    );
  }

  private notifyListeners(): void {
    this.listeners.forEach((fn) => fn());
  }

  private scheduleRefresh(bffClient: BffClient): void {
    this.refreshTimer = setInterval(
      () => void this.refresh(bffClient),
      this.REFRESH_INTERVAL_MS
    );
  }

  destroy(): void {
    if (this.refreshTimer !== null) clearInterval(this.refreshTimer);
    this.listeners.clear();
  }
}

function buildCacheKey(entity: string, options: QueryOptions): string {
  return JSON.stringify({
    entity,
    filter: options.filter ?? null,
    sort: options.sort ?? null,
    fields: options.fields ?? null,
    limit: options.limit ?? 50,
  });
}

// src/cache/QueryCache.ts

interface CacheEntry<T> {
  data: T[] | null;
  pagination: Pagination | null;
  error: AppSDKError | null;
  fetchedAt: number;  // Date.now()
  promise: Promise<void> | null;  // in-flight deduplification
}

class QueryCache {
  private entries = new Map<string, CacheEntry<unknown>>();

  get<T>(key: string): CacheEntry<T> | undefined {
    return this.entries.get(key) as CacheEntry<T> | undefined;
  }

  set<T>(key: string, entry: CacheEntry<T>): void {
    this.entries.set(key, entry as CacheEntry<unknown>);
  }

  isStale(key: string, staleTime: number): boolean {
    const entry = this.entries.get(key);
    if (!entry) return true;
    return Date.now() - entry.fetchedAt > staleTime;
  }

  invalidate(entity: string): void {
    // Invalidate all cache entries for a given entity (called by useMutation after write)
    for (const key of this.entries.keys()) {
      if (key.includes(`"entity":"${entity}"`)) {
        this.entries.delete(key);
      }
    }
  }
}

export const queryCache = new QueryCache();

// src/hooks/useQuery.ts

export function useQuery<T = unknown>(
  entity: string,
  options: QueryOptions = {}
): QueryResult<T> {
  const { bffClient, isReady } = useAppContext();
  const cacheKey = buildCacheKey(entity, options);
  const staleTime = options.staleTime ?? 30_000;

  // useSyncExternalStore for cache-driven re-renders
  const cachedEntry = useSyncExternalStore(
    (notify) => queryCache.subscribe(cacheKey, notify),
    () => queryCache.get<T>(cacheKey),
  );

  const isLoading = !isReady || (cachedEntry === undefined && !cachedEntry?.error);
  const pages = useRef<string[]>([]);  // cursor chain for fetchNextPage

  const fetchPage = useCallback(
    async (cursor?: string, append = false) => {
      const controller = new AbortController();
      const params = buildQueryParams(options, cursor);
      try {
        const result = await bffClient.request<BffDataResponse<T>>(
          `/bff/data/${entity}`,
          { queryParams: params, signal: controller.signal }
        );
        queryCache.set(cacheKey, {
          data: append
            ? [...(queryCache.get<T>(cacheKey)?.data ?? []), ...result.data]
            : result.data,
          pagination: result.pagination,
          error: null,
          fetchedAt: Date.now(),
          promise: null,
        });
      } catch (err) {
        if ((err as Error).name === "AbortError") return;
        const sdkError = err as AppSDKError;
        queryCache.set(cacheKey, {
          data: cachedEntry?.data ?? null,
          pagination: cachedEntry?.pagination ?? null,
          error: sdkError,
          fetchedAt: Date.now(),
          promise: null,
        });
        options.onError?.(sdkError);
      }
    },
    [entity, cacheKey, bffClient, options]
  );

  // Initial fetch and stale-while-revalidate
  useEffect(() => {
    if (!isReady || options.enabled === false) return;
    if (queryCache.isStale(cacheKey, staleTime)) {
      void fetchPage(undefined, false);
    }
  }, [isReady, options.enabled, cacheKey, staleTime, fetchPage]);

  const refetch = useCallback(() => fetchPage(undefined, false), [fetchPage]);

  const fetchNextPage = useCallback(async () => {
    const cursor = cachedEntry?.pagination?.nextCursor;
    if (!cursor) return;
    await fetchPage(cursor, true);
  }, [cachedEntry, fetchPage]);

  return {
    data: cachedEntry?.data ?? null,
    pagination: cachedEntry?.pagination ?? null,
    isLoading: isLoading && !cachedEntry,
    isError: !!cachedEntry?.error,
    error: cachedEntry?.error ?? null,
    refetch,
    fetchNextPage,
  };
}

export function useMutation<T = unknown>(entity: string): MutationResult<T> {
  const { bffClient } = useAppContext();
  const [state, setState] = useState<MutationState>({
    isLoading: false,
    isError: false,
    error: null,
  });

  const mutationQueue = useRef<Promise<void>>(Promise.resolve());

  function enqueue<R>(fn: () => Promise<R>): Promise<R> {
    let resolve!: (v: R) => void;
    let reject!: (e: unknown) => void;
    const p = new Promise<R>((res, rej) => { resolve = res; reject = rej; });
    mutationQueue.current = mutationQueue.current.then(async () => {
      try { resolve(await fn()); } catch (e) { reject(e); }
    });
    return p;
  }

  const create = useCallback((data: Partial<T>): Promise<T> => {
    return enqueue(async () => {
      setState({ isLoading: true, isError: false, error: null });
      const snapshot = queryCache.snapshot(entity);
      const optimisticId = `_opt_${crypto.randomUUID()}`;
      queryCache.optimisticCreate(entity, { ...data, _optimisticId: optimisticId });
      try {
        const result = await bffClient.request<T>(`/bff/data/${entity}`, {
          method: "POST",
          body: data,
        });
        queryCache.confirmCreate(entity, optimisticId, result as Record<string, unknown>);
        setState({ isLoading: false, isError: false, error: null });
        return result;
      } catch (err) {
        queryCache.restoreSnapshot(entity, snapshot);
        const sdkError = err as AppSDKError;
        setState({ isLoading: false, isError: true, error: sdkError });
        throw sdkError;
      }
    });
  }, [entity, bffClient]);

  // update, replace, remove, bulkCreate follow the same pattern
  // ...

  return {
    create,
    update: /* ... */,
    replace: /* ... */,
    remove: /* ... */,
    bulkCreate: /* ... */,
    isLoading: state.isLoading,
    isError: state.isError,
    error: state.error,
    reset: () => setState({ isLoading: false, isError: false, error: null }),
  };
}

// src/ws/WebSocketManager.ts

interface SubscriptionRegistration {
  entity: string;
  filter?: FilterSpec;
  events?: EntityEventType[];
  onEvent: (event: EntityEvent<unknown>) => void;
}

class WebSocketManager {
  private socket: WebSocket | null = null;
  private registrations = new Map<string, SubscriptionRegistration>();
  private reconnectAttempts = 0;
  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
  private statusListeners = new Set<(connected: boolean, attempts: number) => void>();
  private readonly MAX_RECONNECT_DELAY_MS = 30_000;
  private readonly BASE_RECONNECT_DELAY_MS = 1_000;

  connect(appSlug: string): void {
    const url = `${window.location.origin.replace(/^http/, "ws")}/apps/${appSlug}/ws`;
    this.socket = new WebSocket(url);
    this.socket.addEventListener("open", this.onOpen);
    this.socket.addEventListener("message", this.onMessage);
    this.socket.addEventListener("close", this.onClose);
    this.socket.addEventListener("error", this.onError);
  }

  register(id: string, reg: SubscriptionRegistration): void {
    this.registrations.set(id, reg);
    if (this.socket?.readyState === WebSocket.OPEN) {
      this.send({ type: "subscribe", subscriptionId: id, entity: reg.entity, filter: reg.filter, events: reg.events });
    }
    // If not connected, registrations are replayed in onOpen
  }

  unregister(id: string): void {
    this.registrations.delete(id);
    if (this.socket?.readyState === WebSocket.OPEN) {
      this.send({ type: "unsubscribe", subscriptionId: id });
    }
  }

  private onOpen = (): void => {
    this.reconnectAttempts = 0;
    this.notifyStatus(true, 0);
    // Replay all registrations (handles reconnect case)
    for (const [id, reg] of this.registrations) {
      this.send({ type: "subscribe", subscriptionId: id, entity: reg.entity, filter: reg.filter, events: reg.events });
    }
  };

  private onMessage = (event: MessageEvent): void => {
    let msg: EntityEvent<unknown> & { subscriptionId?: string };
    try { msg = JSON.parse(event.data as string); } catch { return; }
    const reg = this.registrations.get(msg.subscriptionId ?? "");
    if (reg) reg.onEvent(msg);
  };

  private onClose = (): void => {
    this.notifyStatus(false, this.reconnectAttempts);
    this.scheduleReconnect();
  };

  private scheduleReconnect(): void {
    const delay = Math.min(
      this.BASE_RECONNECT_DELAY_MS * 2 ** this.reconnectAttempts,
      this.MAX_RECONNECT_DELAY_MS
    );
    this.reconnectAttempts++;
    this.reconnectTimer = setTimeout(() => {
      const slug = this.extractSlug();
      if (slug) this.connect(slug);
    }, delay);
  }

  destroy(): void {
    if (this.reconnectTimer !== null) clearTimeout(this.reconnectTimer);
    this.socket?.close();
    this.statusListeners.clear();
  }
}

// src/hooks/useSubscription.ts

export function useSubscription<T = unknown>(
  entity: string,
  options: SubscriptionOptions = {}
): SubscriptionResult<T> {
  const { wsManager } = useAppContext();
  const id = useId();  // React 18 stable ID
  const [lastEvent, setLastEvent] = useState<EntityEvent<T> | null>(null);

  const [status, setStatus] = useSyncExternalStore(
    (notify) => wsManager.subscribeToStatus(notify),
    () => wsManager.getStatus(),
  );

  useEffect(() => {
    wsManager.register(id, {
      entity,
      filter: options.filter,
      events: options.events,
      onEvent: (event) => {
        setLastEvent(event as EntityEvent<T>);
        options.onEvent?.(event);
      },
    });
    return () => wsManager.unregister(id);
  }, [id, entity, wsManager]);
  // options.filter, options.events, options.onEvent are intentionally excluded
  // from deps to avoid re-registering on every render if caller passes literals.
  // Callers must memoize options if they need dynamic filter changes.

  return {
    lastEvent,
    isConnected: status.isConnected,
    reconnectAttempts: status.reconnectAttempts,
  };
}

// src/hooks/useUser.ts

export function useUser(): UserContext {
  const { user } = useAppContext();

  if (user === null) {
    // AppProvider is still loading (isReady: false). Return a safe sentinel value.
    return {
      id: "",
      email: null,
      displayName: "",
      tenantId: "",
      roles: [],
      isGuest: false,
    };
  }

  return user;
}

// src/hooks/usePermission.ts

export function usePermission(
  action: PermissionAction | string,
  resource: string
): boolean {
  const { permissionCache } = useAppContext();

  // useSyncExternalStore ensures re-render when cache is refreshed
  return useSyncExternalStore(
    (notify) => permissionCache.subscribe(notify),
    () => permissionCache.check(action, resource),
  );
}