fix: route v2 callables through wrapV2 when platform is gcfv2

[IzaakGough]

Fixes #310

Summary

Fixes wrap() misrouting v2 onCall functions to the v1 test helper when used with firebase-functions@7.x.

wrap() previously chose between wrapV2 and wrapV1 using Function.length i.e.

cloudFunction.length === 1 && cloudFunction.run.length === 1

In firebase-functions@7, v2 callables are wrapped with rest-parameter helpers (withInit, wrapTraceContext), so both lengths are 0. wrap() fell through to wrapV1, which invokes run(data, context) instead of
run({ data, auth, ... }), breaking auth and other CallableRequest fields in unit tests.

Affected versions: firebase-functions-test@3.4.1, 3.5.0 (and any release using the arity-only heuristic without this fix).

Issue reproduced here: MRE

Problem

With firebase-functions@7 + firebase-functions-test@3.4.1 / 3.5.0:

1. Define a v2 callable with onCall() that checks request.auth
2. Wrap it with wrap() and call it with an auth context
3. The handler never receives request.auth → spurious permission-denied errors

Root cause: isV2CloudFunction returns false for real v2 callables, so wrapV1 is used for a v2 handler.

Solution

• Route v2 callables to wrapV2 before the arity check, using stable SDK metadata:
  • __endpoint.callableTrigger
  • __endpoint.platform === 'gcfv2' (v1 callables also have callableTrigger but use gcfv1)
• Export isCallableV2Function from src/v2.ts for reuse and tests
• Broaden isV2CloudFunction to also return true when platform === 'gcfv2', so other v2 triggers (Pub/Sub, alerts, etc.) are not misrouted when .length === 0

What changed vs original wrap()

Original behavior

if (isV2CloudFunction(cloudFunction)) {
  return wrapV2(cloudFunction);  // v2 path
}
return wrapV1(cloudFunction);    // everything else, including misrouted v2 callables

isV2CloudFunction was only:

cloudFunction.length === 1 && cloudFunction.run?.length === 1

New behavior

if (isCallableV2Function(cloudFunction)) {
  const v2Callable = cloudFunction as CallableFunction<any, T>;
  return wrapV2(v2Callable);
}
if (isV2CloudFunction(cloudFunction)) {
  return wrapV2(cloudFunction as CloudFunctionV2<V>);
}
return wrapV1(cloudFunction);

isCallableV2Function (new, exported from src/v2.ts):

!!cf?.__endpoint?.callableTrigger && cf.__endpoint.platform === 'gcfv2'

isV2CloudFunction (updated):

if (cloudFunction?.__endpoint?.platform === 'gcfv2') {
  return true;
}
return cloudFunction.length === 1 && cloudFunction?.run?.length === 1;

Routing flow

Scenario	Original	After fix
v2 onCall + wrap(fn)({ data, auth })	Often wrapV1 → run(data, context) → auth broken	wrapV2 → run({ data, auth }) → auth works
v1 onCall (callableTrigger, gcfv1)	wrapV1 → (data, { auth })	Unchanged
v2 Pub/Sub / alerts with length === 0	Could hit wrapV1	platform === 'gcfv2' → wrapV2

For v2 callables, wrapV2 invokes:

(req: CallableRequest) => cloudFunction.run(req)

The as CallableFunction cast is for TypeScript only (wrap() accepts a broad union; wrapV2 has separate overloads for callables vs event functions).

Files changed

File	Change
src/main.ts	Early isCallableV2Function branch in wrap(); isV2CloudFunction checks platform === 'gcfv2'
src/v2.ts	Export isCallableV2Function with callableTrigger + gcfv2 platform guard
spec/main.spec.ts	Regression test: v2 callable with outer/run length === 0 routes to v2 path

Test plan

• npm test (all 119 tests pass)
• [ ]

Backward compatibility

• v1 callables: unchanged — still routed via wrapV1 (platform is gcfv1 or absent)
• v2 callables: now correctly use wrapV2 single-argument CallableRequest API
• v2 event functions: improved routing when platform === 'gcfv2' and arity heuristic fails

[gemini-code-assist]

Code Review

This pull request introduces support for identifying and wrapping GCFv2 callable functions by checking the platform field in the endpoint metadata. Key changes include exporting the isCallableV2Function utility, updating the wrap function to prioritize v2 callable detection, and adding a corresponding test case in spec/main.spec.ts to ensure correct routing. There are no review comments to address, and I have no further feedback to provide.

[cabljac]

This looks great. The __endpoint.platform === 'gcfv2' check is a much more stable signal than counting function parameters, and the regression test covers the routing path nicely. A couple of small questions below, neither blocking.