@proulr/bff-core 0.1.1 → 0.1.5

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@proulr/bff-core",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing/index.ts"
   },
   "files": [
     "src"
@@ -15,22 +16,39 @@
     "url": "git+https://github.com/saviorbp/proulr-bff-core.git"
   },
   "scripts": {
+    "prepare": "husky",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "version:sync": "node ../scripts/proulr-bump-and-sync-deps.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
-    "@proulr/sdui-contract": "^0.1.0",
+    "@proulr/rosetta": "^0.1.4",
+    "@proulr/sdui-contract": "^0.1.5",
     "@supabase/supabase-js": "^2.107.0",
     "dotenv": "^16.6.1",
     "hono": "^4.10.6",
     "prom-client": "^15.1.3"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@types/node": "^22.10.0",
-    "typescript": "~6.0.3"
+    "eslint": "^9.0.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { createSduiBff } from './index';
+import { createScreenBuilderContext } from './testing/create-screen-builder-context';
+import { createMockSupabaseClient } from './testing/create-mock-supabase-client';
+
+describe('createSduiBff', () => {
+  it('serves /health with registered screens', async () => {
+    const { app } = createSduiBff({
+      name: 'Test BFF',
+      port: 9999,
+      bffId: 'test-bff',
+      screens: {
+        'demo.home': async () => ({
+          schema_version: 1,
+          screen_id: 'demo.home',
+          blocks: [],
+        }),
+      },
+    });
+
+    const response = await app.request('/health');
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body).toMatchObject({
+      ok: true,
+      bff: 'test-bff',
+      name: 'Test BFF',
+      screens: ['demo.home'],
+    });
+  });
+
+  it('returns 404 for unknown screen', async () => {
+    const { app } = createSduiBff({
+      name: 'Test BFF',
+      port: 9999,
+      bffId: 'test-bff',
+      screens: {},
+    });
+
+    const response = await app.request('/v1/screens/missing');
+    expect(response.status).toBe(404);
+    const body = await response.json();
+    expect(body).toMatchObject({ error: 'screen_not_found', screen_id: 'missing' });
+  });
+
+  it('returns 404 stub for unknown action', async () => {
+    const { app } = createSduiBff({
+      name: 'Test BFF',
+      port: 9999,
+      bffId: 'test-bff',
+      screens: {},
+    });
+
+    const response = await app.request('/v1/actions/noop', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(404);
+    const body = await response.json();
+    expect(body).toMatchObject({ ok: false, error: 'action_not_found', action_id: 'noop' });
+  });
+
+  it('invokes registered screen builder with auth token', async () => {
+    let seenToken: string | undefined;
+    const { app } = createSduiBff({
+      name: 'Test BFF',
+      port: 9999,
+      bffId: 'test-bff',
+      screens: {
+        'demo.home': async (ctx) => {
+          seenToken = ctx.authToken;
+          return {
+            schema_version: 1,
+            screen_id: 'demo.home',
+            blocks: [{ id: 'root', type: 'stack', props: {} }],
+          };
+        },
+      },
+    });
+
+    const response = await app.request('/v1/screens/demo.home', {
+      headers: { Authorization: 'Bearer tok-123' },
+    });
+    expect(response.status).toBe(200);
+    expect(seenToken).toBe('tok-123');
+    const body = await response.json();
+    expect(body.screen_id).toBe('demo.home');
+  });
+});
+
+describe('testing helpers', () => {
+  it('createScreenBuilderContext defaults empty maps', () => {
+    expect(createScreenBuilderContext({ authToken: 'a' })).toEqual({
+      authToken: 'a',
+      query: {},
+      routeParams: {},
+    });
+  });
+
+  it('createMockSupabaseClient resolves table and rpc results', async () => {
+    const client = createMockSupabaseClient({
+      fromResults: {
+        profiles: { data: { id: '1' }, error: null },
+      },
+      rpcResults: {
+        ping: { data: true, error: null },
+      },
+    });
+
+    const profile = await client.from('profiles').select('*').eq('id', '1').maybeSingle();
+    expect(profile.data).toEqual({ id: '1' });
+
+    const rpc = await client.rpc('ping');
+    expect(rpc.data).toBe(true);
+  });
+});

package/src/index.ts

@@ -5,11 +5,17 @@ import { cors } from 'hono/cors';
 import type { SduiScreenBuilder, SduiScreenBuilderContext } from '@proulr/sdui-contract';
 import { createBffMetrics, isBffMetricsEnabled } from './bff-metrics';
 
+export type SduiActionHandler = (
+  ctx: SduiScreenBuilderContext,
+  body: Record<string, unknown>,
+) => Promise<Record<string, unknown>>;
+
 export type CreateSduiBffOptions = {
   name: string;
   port: number;
   bffId: string;
   screens: Record<string, SduiScreenBuilder>;
+  actions?: Record<string, SduiActionHandler>;
 };
 
 function buildContext(
@@ -107,13 +113,34 @@ export function createSduiBff(options: CreateSduiBffOptions) {
 
   app.post('/v1/actions/:actionId', async (c) => {
     const actionId = c.req.param('actionId');
-    const body = await c.req.json().catch(() => ({}));
-    return c.json({
-      ok: true,
-      action_id: actionId,
-      received: body,
-      message: 'Action endpoint stub — implement per domain in each BFF.',
-    });
+    const body = (await c.req.json().catch(() => ({}))) as Record<string, unknown>;
+    const handler = options.actions?.[actionId];
+
+    if (!handler) {
+      return c.json({
+        ok: false,
+        action_id: actionId,
+        error: 'action_not_found',
+        message: 'Action endpoint stub — register handler in BFF actions map.',
+      }, 404);
+    }
+
+    try {
+      const authToken = readAuthToken(c.req.header('Authorization'));
+      const result = await handler(buildContext({}, {}, authToken), body);
+      return c.json({ ok: true, action_id: actionId, ...result });
+    } catch (error) {
+      console.warn(`[${options.bffId}] action ${actionId} failed`, error);
+      return c.json(
+        {
+          ok: false,
+          action_id: actionId,
+          error: 'action_failed',
+          message: error instanceof Error ? error.message : 'action_failed',
+        },
+        500,
+      );
+    }
   });
 
   return {
@@ -128,3 +155,13 @@ export function createSduiBff(options: CreateSduiBffOptions) {
 
 export * from '@proulr/sdui-contract';
 export { createBffSupabaseClient, isBffSupabaseConfigured } from './bff-supabase-client';
+export {
+  buildNativeAdInsertionSeed,
+  insertRandomNativeAdSlots,
+  type InsertRandomNativeAdSlotsOptions,
+  type NativeAdSlotWire,
+} from './native-ad-slot-insertion';
+export {
+  resolveLocaleFromQuery,
+  type ProulrLocale,
+} from '@proulr/rosetta';

package/src/native-ad-slot-insertion.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildNativeAdInsertionSeed,
+  insertRandomNativeAdSlots,
+} from './native-ad-slot-insertion';
+
+describe('buildNativeAdInsertionSeed', () => {
+  it('joins non-empty parts with colon', () => {
+    expect(buildNativeAdInsertionSeed(['feed', '', 'user-1'])).toBe('feed:user-1');
+  });
+});
+
+describe('insertRandomNativeAdSlots', () => {
+  it('returns a copy when feed is too short for ads', () => {
+    const items = [1, 2];
+    const result = insertRandomNativeAdSlots(items, {
+      placement: 'feed',
+      seed: 'a',
+      minContentBeforeFirstAd: 2,
+    });
+    expect(result).toEqual([1, 2]);
+    expect(result).not.toBe(items);
+  });
+
+  it('is deterministic for the same seed', () => {
+    const items = Array.from({ length: 40 }, (_, index) => index);
+    const options = {
+      placement: 'discover',
+      seed: 'stable-seed',
+      minContentBeforeFirstAd: 2,
+      minGap: 4,
+      maxGap: 6,
+      maxAds: 3,
+    };
+    const first = insertRandomNativeAdSlots(items, options);
+    const second = insertRandomNativeAdSlots(items, options);
+    expect(first).toEqual(second);
+    expect(first.some((item) => typeof item === 'object' && item !== null && 'kind' in item && item.kind === 'ad')).toBe(
+      true,
+    );
+  });
+});

package/src/native-ad-slot-insertion.ts

@@ -0,0 +1,90 @@
+export type NativeAdSlotWire = {
+  kind: 'ad';
+  id: string;
+  placement: string;
+};
+
+export type InsertRandomNativeAdSlotsOptions = {
+  placement: string;
+  seed: string;
+  minContentBeforeFirstAd?: number;
+  minGap?: number;
+  maxGap?: number;
+  maxAds?: number;
+  idPrefix?: string;
+};
+
+function hashSeed(seed: string): number {
+  let hash = 2166136261;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function createSeededRandom(seed: number): () => number {
+  let state = seed || 1;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function randomInt(random: () => number, min: number, max: number): number {
+  if (max <= min) return min;
+  return min + Math.floor(random() * (max - min + 1));
+}
+
+export function buildNativeAdInsertionSeed(parts: string[]): string {
+  return parts.filter(Boolean).join(':');
+}
+
+export function insertRandomNativeAdSlots<T>(
+  items: T[],
+  options: InsertRandomNativeAdSlotsOptions,
+): Array<T | NativeAdSlotWire> {
+  const minContentBeforeFirstAd = options.minContentBeforeFirstAd ?? 2;
+  const minGap = options.minGap ?? 4;
+  const maxGap = options.maxGap ?? 8;
+  const maxAds = options.maxAds ?? Math.max(1, Math.floor(items.length / 12));
+  const idPrefix = options.idPrefix ?? options.placement;
+
+  if (!items.length || items.length < minContentBeforeFirstAd + 1) {
+    return [...items];
+  }
+
+  const random = createSeededRandom(hashSeed(options.seed));
+  const result: Array<T | NativeAdSlotWire> = [];
+  let sourceIndex = 0;
+  let adsInserted = 0;
+  let contentSinceLastAd = 0;
+  let nextAdAfter = randomInt(random, minGap, maxGap);
+
+  while (sourceIndex < items.length) {
+    const shouldInsertAd =
+      adsInserted < maxAds &&
+      contentSinceLastAd >= nextAdAfter &&
+      sourceIndex >= minContentBeforeFirstAd;
+
+    if (shouldInsertAd) {
+      result.push({
+        kind: 'ad',
+        id: `${idPrefix}-ad-${adsInserted}`,
+        placement: options.placement,
+      });
+      adsInserted += 1;
+      contentSinceLastAd = 0;
+      nextAdAfter = randomInt(random, minGap, maxGap);
+      continue;
+    }
+
+    result.push(items[sourceIndex]);
+    sourceIndex += 1;
+    contentSinceLastAd += 1;
+  }
+
+  return result;
+}

package/src/testing/create-mock-supabase-client.ts

@@ -0,0 +1,124 @@
+export type MockQueryResult<T = unknown> = {
+  data: T;
+  error: { message: string; code?: string } | null;
+  count?: number | null;
+  status?: number;
+  statusText?: string;
+};
+
+type ThenableResult<T> = PromiseLike<MockQueryResult<T>> & MockQueryBuilder;
+
+export type MockQueryBuilder = {
+  select: (...args: unknown[]) => MockQueryBuilder;
+  insert: (...args: unknown[]) => MockQueryBuilder;
+  update: (...args: unknown[]) => MockQueryBuilder;
+  upsert: (...args: unknown[]) => MockQueryBuilder;
+  delete: (...args: unknown[]) => MockQueryBuilder;
+  eq: (...args: unknown[]) => MockQueryBuilder;
+  neq: (...args: unknown[]) => MockQueryBuilder;
+  in: (...args: unknown[]) => MockQueryBuilder;
+  is: (...args: unknown[]) => MockQueryBuilder;
+  gt: (...args: unknown[]) => MockQueryBuilder;
+  gte: (...args: unknown[]) => MockQueryBuilder;
+  lt: (...args: unknown[]) => MockQueryBuilder;
+  lte: (...args: unknown[]) => MockQueryBuilder;
+  like: (...args: unknown[]) => MockQueryBuilder;
+  ilike: (...args: unknown[]) => MockQueryBuilder;
+  order: (...args: unknown[]) => MockQueryBuilder;
+  limit: (...args: unknown[]) => MockQueryBuilder;
+  range: (...args: unknown[]) => MockQueryBuilder;
+  single: () => ThenableResult<unknown>;
+  maybeSingle: () => ThenableResult<unknown>;
+  then: PromiseLike<MockQueryResult>['then'];
+};
+
+export type MockSupabaseClientOptions = {
+  /** Default result for any chain that resolves without a table-specific override. */
+  defaultResult?: MockQueryResult;
+  /** Per-table results keyed by table name passed to `.from(table)`. */
+  fromResults?: Record<string, MockQueryResult | (() => MockQueryResult)>;
+  /** Results keyed by RPC function name. */
+  rpcResults?: Record<string, MockQueryResult | ((args?: unknown) => MockQueryResult)>;
+};
+
+function resolveResult(
+  value: MockQueryResult | (() => MockQueryResult) | undefined,
+  fallback: MockQueryResult,
+): MockQueryResult {
+  if (!value) return fallback;
+  return typeof value === 'function' ? value() : value;
+}
+
+function createQueryBuilder(result: MockQueryResult): MockQueryBuilder {
+  const builder: MockQueryBuilder = {} as MockQueryBuilder;
+
+  const chain = (): MockQueryBuilder => builder;
+  const terminal = (): ThenableResult<unknown> =>
+    Object.assign(Promise.resolve(result), builder) as ThenableResult<unknown>;
+
+  builder.select = chain;
+  builder.insert = chain;
+  builder.update = chain;
+  builder.upsert = chain;
+  builder.delete = chain;
+  builder.eq = chain;
+  builder.neq = chain;
+  builder.in = chain;
+  builder.is = chain;
+  builder.gt = chain;
+  builder.gte = chain;
+  builder.lt = chain;
+  builder.lte = chain;
+  builder.like = chain;
+  builder.ilike = chain;
+  builder.order = chain;
+  builder.limit = chain;
+  builder.range = chain;
+  builder.single = terminal;
+  builder.maybeSingle = terminal;
+  builder.then = (onfulfilled, onrejected) =>
+    Promise.resolve(result).then(onfulfilled, onrejected);
+
+  return builder;
+}
+
+export type MockSupabaseClient = {
+  from: (table: string) => MockQueryBuilder;
+  rpc: (fn: string, args?: unknown) => ThenableResult<unknown>;
+  auth: {
+    getUser: () => Promise<{ data: { user: { id: string } | null }; error: null }>;
+  };
+};
+
+/**
+ * Lightweight chainable Supabase stub for BFF unit/integration tests.
+ * Configure per-table / RPC results; unresolved tables use `defaultResult`.
+ */
+export function createMockSupabaseClient(
+  options: MockSupabaseClientOptions = {},
+): MockSupabaseClient {
+  const defaultResult: MockQueryResult = options.defaultResult ?? {
+    data: null,
+    error: null,
+  };
+
+  return {
+    from(table: string) {
+      const tableResult = resolveResult(options.fromResults?.[table], defaultResult);
+      return createQueryBuilder(tableResult);
+    },
+    rpc(fn: string, args?: unknown) {
+      const rpcEntry = options.rpcResults?.[fn];
+      const result =
+        typeof rpcEntry === 'function'
+          ? rpcEntry(args)
+          : (rpcEntry ?? defaultResult);
+      return Object.assign(Promise.resolve(result), createQueryBuilder(result)) as ThenableResult<unknown>;
+    },
+    auth: {
+      async getUser() {
+        return { data: { user: { id: 'test-user-id' } }, error: null };
+      },
+    },
+  };
+}

package/src/testing/create-screen-builder-context.ts

@@ -0,0 +1,17 @@
+import type { SduiScreenBuilderContext } from '@proulr/sdui-contract';
+
+export type CreateScreenBuilderContextOptions = {
+  authToken?: string;
+  query?: Record<string, string>;
+  routeParams?: Record<string, string>;
+};
+
+export function createScreenBuilderContext(
+  options: CreateScreenBuilderContextOptions = {},
+): SduiScreenBuilderContext {
+  return {
+    authToken: options.authToken,
+    query: options.query ?? {},
+    routeParams: options.routeParams ?? {},
+  };
+}

package/src/testing/create-test-sdui-bff.ts

@@ -0,0 +1,6 @@
+import { createSduiBff, type CreateSduiBffOptions } from '../index';
+
+/** Thin wrapper — same as `createSduiBff`; use `app.request` without calling `start()`. */
+export function createTestSduiBff(options: CreateSduiBffOptions) {
+  return createSduiBff(options);
+}

package/src/testing/index.ts

@@ -0,0 +1,12 @@
+export {
+  createMockSupabaseClient,
+  type MockQueryBuilder,
+  type MockQueryResult,
+  type MockSupabaseClient,
+  type MockSupabaseClientOptions,
+} from './create-mock-supabase-client';
+export {
+  createScreenBuilderContext,
+  type CreateScreenBuilderContextOptions,
+} from './create-screen-builder-context';
+export { createTestSduiBff } from './create-test-sdui-bff';