PROTM-2267: Add bounded-sampling API for S3/GCS/DynamoDB datasources

[sandshoes]

Summary

• Adds a sampleDatasource method to TinybirdApi (src/api/api.ts) that POSTs to /v0/datasources/{datasourceName}/sample with {max_files, full_export, rows?, max_bytes?}, mirroring the raw HTTP shape used by tb datasource sample.
• Exposes this via client.datasources.sample(datasourceName, options) in TinybirdClient (src/client/base.ts), following the same append/delete/truncate pattern (resolve token → call API layer → rethrow TinybirdApiError as TinybirdError).
• Adds SampleOptions/SampleResult types to src/client/types.ts and TinybirdApiSampleOptions to src/api/api.ts, all exported from src/index.ts.
• Closes the Python/TypeScript SDK parity gap: the Python SDK already shipped sample_datasource with this exact request shape.

Closes https://linear.app/tinybird/issue/PROTM-2267/typescript-sdk-add-bounded-sampling-api-for-s3gcsdynamodb-datasources

Design notes

• Method naming: TinybirdApi.sampleDatasource / client.datasources.sample, matching the existing appendDatasource/client.datasources.append, deleteDatasource/client.datasources.delete, etc. pairing.
• Options use camelCase (maxFiles, maxBytes, fullExport) at the TS API surface, matching this SDK's existing convention (e.g. deleteCondition, dryRun), while the JSON body sent over the wire uses the Python SDK's snake_case field names (max_files, full_export, rows, max_bytes) to match the Tinybird API contract exactly.
• rows and maxBytes are mutually exclusive (DynamoDB-only): passing both throws synchronously before any request is made, matching the Python SDK's ValueError behavior (ported as a plain Error, consistent with this SDK's other client-side validation like the missing-deleteCondition check).
• Defaults match Python: maxFiles defaults to 1, fullExport defaults to false.

Out of scope

• No CLI command wrapper (tinybird datasource sample) — the issue only asked for the SDK-level API, matching how other datasource operations (delete/truncate) were added without CLI commands.
• No runtime validation of maxFiles bounds (e.g. max 10) — left to the Tinybird API to enforce and return as an error, same as the Python SDK.

Test plan

• pnpm typecheck
• pnpm test:run (1072 tests passing, including new sampleDatasource coverage in src/api/api.test.ts for defaults, maxFiles, DynamoDB rows, DynamoDB maxBytes, fullExport, the mutual-exclusion error, and per-request token override)
• pnpm build

🤖 Generated with Claude Code