@proulr/bff-core 0.1.2 → 0.1.7

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@proulr/bff-core",
-  "version": "0.1.2",
+  "version": "0.1.7",
   "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,43 @@
     "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",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:integration:coverage": "vitest run --config vitest.integration.config.ts --coverage",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "version:sync": "node ../scripts/proulr-bump-and-sync-deps.mjs",
+    "test:coverage": "vitest run --coverage"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
-    "@proulr/sdui-contract": "^0.1.0",
+    "@proulr/rosetta": "^0.1.5",
+    "@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"
+    "@vitest/coverage-v8": "^3.2.7",
+    "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.integration.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+type ServeCallback = (info: { address: string; family: string; port: number }) => void;
+
+const serveMock = vi.fn((opts: unknown, cb?: ServeCallback) => {
+  void opts;
+  cb?.({ address: '0.0.0.0', family: 'IPv4', port: 9999 });
+  return { close: vi.fn() };
+});
+
+vi.mock('@hono/node-server', () => ({
+  serve: (opts: unknown, cb?: ServeCallback) => serveMock(opts, cb),
+}));
+
+import { createSduiBff } from './index';
+
+function createTestApp(overrides?: {
+  metricsEnv?: string;
+  actions?: Parameters<typeof createSduiBff>[0]['actions'];
+}) {
+  if (overrides?.metricsEnv !== undefined) {
+    vi.stubEnv('BFF_METRICS', overrides.metricsEnv);
+  }
+  return createSduiBff({
+    name: 'Integration BFF',
+    port: 9999,
+    bffId: 'integration-bff',
+    screens: {
+      'demo.home': async (ctx) => ({
+        schema_version: 1,
+        screen_id: 'demo.home',
+        blocks: [],
+        data: {
+          auth_token: ctx.authToken ?? null,
+          locale: ctx.query?.locale ?? null,
+        },
+        meta: { bff: 'integration-bff' },
+      }),
+    },
+    actions: overrides?.actions ?? {
+      ping: async (_ctx, body) => ({ echo: body }),
+      boom: async () => {
+        throw new Error('boom_failed');
+      },
+      boom_string: async () => {
+        throw 'string_error';
+      },
+    },
+  });
+}
+
+describe('createSduiBff HTTP integration', () => {
+  beforeEach(() => {
+    serveMock.mockClear();
+    vi.unstubAllEnvs();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('serves /health with screens and metrics flag', async () => {
+    const { app } = createTestApp({ metricsEnv: '1' });
+    const response = await app.request('/health');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('X-Request-Id')).toBeTruthy();
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      bff: 'integration-bff',
+      name: 'Integration BFF',
+      screens: ['demo.home'],
+      metrics_enabled: true,
+    });
+  });
+
+  it('returns screen wire and parses Bearer auth + query', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/screens/demo.home?locale=pt-BR', {
+      headers: { Authorization: 'Bearer  tok-abc  ' },
+    });
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.screen_id).toBe('demo.home');
+    expect(body.data).toMatchObject({ auth_token: 'tok-abc', locale: 'pt-BR' });
+  });
+
+  it('ignores non-Bearer Authorization header', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/screens/demo.home', {
+      headers: { Authorization: 'Basic abc' },
+    });
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.data.auth_token).toBeNull();
+  });
+
+  it('returns 404 for unknown screen', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/screens/missing.screen');
+    expect(response.status).toBe(404);
+    await expect(response.json()).resolves.toMatchObject({
+      error: 'screen_not_found',
+      screen_id: 'missing.screen',
+    });
+  });
+
+  it('invokes registered action with auth and body', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/actions/ping', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: 'Bearer act-tok',
+      },
+      body: JSON.stringify({ n: 1 }),
+    });
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      action_id: 'ping',
+      echo: { n: 1 },
+    });
+  });
+
+  it('returns 404 stub for unknown action', async () => {
+    const { app } = createTestApp({ actions: {} });
+    const response = await app.request('/v1/actions/noop', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(404);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: false,
+      error: 'action_not_found',
+      action_id: 'noop',
+    });
+  });
+
+  it('returns 500 when action throws Error', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/actions/boom', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(500);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: false,
+      error: 'action_failed',
+      message: 'boom_failed',
+      action_id: 'boom',
+    });
+  });
+
+  it('returns 500 with fallback message for non-Error throw', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/actions/boom_string', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+    expect(response.status).toBe(500);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: false,
+      error: 'action_failed',
+      message: 'action_failed',
+    });
+  });
+
+  it('accepts invalid JSON action body as empty object', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/actions/ping', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{not-json',
+    });
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      echo: {},
+    });
+  });
+
+  it('serves /metrics when metrics enabled', async () => {
+    const { app } = createTestApp({ metricsEnv: '1' });
+    await app.request('/health');
+    const response = await app.request('/metrics');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toContain('text/plain');
+    const text = await response.text();
+    expect(text).toContain('bff_http_requests_total');
+  });
+
+  it('does not register /metrics when BFF_METRICS=0', async () => {
+    const { app } = createTestApp({ metricsEnv: '0' });
+    const health = await app.request('/health');
+    await expect(health.json()).resolves.toMatchObject({ metrics_enabled: false });
+    const metrics = await app.request('/metrics');
+    expect(metrics.status).toBe(404);
+  });
+
+  it('start() binds via @hono/node-server serve', () => {
+    const { start } = createTestApp({ metricsEnv: '0' });
+    start();
+    expect(serveMock).toHaveBeenCalledOnce();
+    expect(serveMock.mock.calls[0]?.[0]).toMatchObject({
+      port: 9999,
+      hostname: '0.0.0.0',
+    });
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { createScreenBuilderContext } from './testing/create-screen-builder-context';
+import { createMockSupabaseClient } from './testing/create-mock-supabase-client';
+import { createTestSduiBff } from './testing/create-test-sdui-bff';
+
+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);
+  });
+
+  it('createTestSduiBff exposes app.request without start', async () => {
+    const { app } = createTestSduiBff({
+      name: 'Unit',
+      port: 1,
+      bffId: 'unit',
+      screens: {},
+    });
+    const response = await app.request('/health');
+    expect(response.status).toBe(200);
+  });
+});

package/src/index.ts

@@ -161,3 +161,7 @@ export {
   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/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';