SDK roadmap

YT2Text is API-first today. The stable integration path is the REST API documented in:

• /guide/authentication
• /api/videos
• /api/batch
• /api/usage
• /api/webhooks

Current status

• REST API is the officially supported path.
• Client SDK packages are planned but not yet published as first-party packages in this repository.

Planned SDK names

• Python: yt2text (PyPI)
• JavaScript/TypeScript: yt2text (npm)

Additional language clients may be added later (Swift/Kotlin/docs examples may remain advisory until release).

Security and auth requirement

Any SDK wrapper must authenticate every request using headers only:

• Authorization: Bearer <api_key> or
• X-API-Key: <api_key>

There is no support for query parameter authentication.

SDKs should treat API keys as secrets and should not embed them in client-side apps.

Public SDK TODO plan (TypeScript + Python)

Goal: ship official TS and Python SDKs that let users go from API key to production deployment in minutes.

Phase 1: Foundation (Week 1)

• Finalize package names and ownership:
  • TS: yt2text on npm
  • Python: yt2text on PyPI
• Create SDK repos (or monorepo packages) with LICENSE, README, CHANGELOG, CONTRIBUTING.
• Define semantic versioning policy (v1.x stable API contract).
• Add generated API types/models from the OpenAPI spec as the single source of truth.

Phase 2: Core client parity (Week 1-2)

• Implement auth configuration (apiKey, custom baseUrl, request timeout).
• Implement Videos endpoints (process, status, result) with typed responses.
• Implement Batch endpoints (process, status, results, list).
• Implement Usage endpoints (current usage/limits).
• Implement Webhook signature verification helper for X-Webhook-Signature.

Phase 3: DX and reliability (Week 2)

• Add automatic retries for 429 + idempotent 5xx responses with exponential backoff.
• Add strongly typed error classes (map API error.code values).
• Add polling helper (waitForResult(jobId, { intervalMs, timeoutMs })).
• Add request ID exposure for debugging/log correlation.

Phase 4: Super-easy deployment path (Week 2-3)

• Ship copy-paste quickstart for both SDKs (3-minute deploy).
• Provide one-command starter templates:
  • TS: Vercel/Node function template
  • Python: FastAPI/Cloud Run template
• Add .env.example + secret management guidance for production.
• Add webhook receiver examples with signature verification enabled by default.
• Publish Docker examples for both SDKs (minimal production image + healthcheck).

Phase 5: CI/CD and release automation (Week 3)

• Add test matrix (Node LTS versions + Python 3.10-3.13).
• Add integration tests against staging API.
• Add automated publish workflows:
  • npm provenance + release tags
  • PyPI trusted publisher + release tags
• Add prerelease channel (next / beta) before GA.
• Add release checklist (smoke tests, docs sync, announcement).

Phase 6: GA readiness (Week 3-4)

• Documentation landing pages updated with real install commands and live examples.
• Support policy and deprecation policy published.
• Postman collection parity confirmed with both SDKs.
• Final migration guide: raw REST -> TS/Python SDK.

Future notes

When first-party SDKs are released, release notes will link package URLs and example auth setup for production apps.