Skip to content

SessionCreateParams.api_timeout is the only snake_case param in the SDK — should be apiTimeout #214

Description

@kang8

In 78f6fab (released in 2.17.0), SessionCreateParams.timeout was renamed to api_timeout. The new name is snake_case, which doesn't match the rest of this SDK.

As far as I can tell it's the only snake_case identifier in the public type surface — grepping resources/**/*.d.ts in 2.18.0 for snake_case params returns exactly one hit. Every sibling field in the same interface is camelCase:

export interface SessionCreateParams {
  projectId?: string;
  browserSettings?: SessionCreateParams.BrowserSettings;
  extensionId?: string;
  keepAlive?: boolean;
  proxySettings?: SessionCreateParams.ProxySettings;
  region?: 'us-west-2' | ...;
  api_timeout?: number;   // <-- odd one out
  userMetadata?: { [key: string]: unknown };
}

The same alias reads perfectly naturally in the Python SDK (sessions.py), where snake_case is the convention — which suggests the alias was defined once in the shared OpenAPI spec rather than per-language. (The commit changes openapi_spec_hash but leaves config_hash untouched.) If it can be expressed per-language, apiTimeout for TypeScript would keep both SDKs idiomatic.

Worth noting as well: the collision the rename avoids doesn't really exist in the Node SDK. The body param and the request-level timeout live in separate positional arguments, so they never shadowed each other:

create(params?: SessionCreateParams, options?: Core.RequestOptions)
//     ^ session timeout               ^ request timeout

So plain timeout would work here too — but apiTimeout is fine and keeps parity with the other SDKs' intent.

I understand renaming again is itself a breaking change for anyone already on 2.17+, so the next major would be a natural place for it rather than a patch.

Context: we hit this in production when a dependency bot moved us 2.16.0 → 2.18.0 and the TypeScript build broke. Minimal repro on 2.17.0 or later:

await bb.sessions.create({ projectId, timeout: 120 });

Because create() is overloaded, TS reports TS2769 No overload matches this call and never surfaces the new name — the error text doesn't contain api_timeout anywhere, and the second overload's complaint ('projectId' does not exist in type 'RequestOptions') is pure noise. So there's no in-editor hint pointing at the migration:

error TS2769: No overload matches this call.
  Overload 1 of 2, '(params?: SessionCreateParams, options?: RequestOptions): ...', gave the following error.
    Object literal may only specify known properties, and 'timeout' does not exist in type 'SessionCreateParams'.
  Overload 2 of 2, '(options?: RequestOptions): ...', gave the following error.
    Object literal may only specify known properties, and 'projectId' does not exist in type 'RequestOptions<unknown>'.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions