Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a client-facing SDK usage guide covering auth, pagination, errors, and rate limits

Open
  • Is something wrong?
#235 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
python, typescript
Domain
api, authentication, documentation

Research direction

Start with the SDK section of README.md (lines 46-86) and the contents of examples/, then read docs/GRAPHQL_GATEWAY.md for the cursor pagination it already documents. Check the webhook signature scheme in src/infrastructure/webhooks/services/webhook-hmac.service.ts. Done means docs/SDK_GUIDE.md covers auth, errors, pagination, rate limits and webhooks, every example runs against a local instance, and the README links to it. The token-refresh section should wait for the linked token-expiry issue.

Written by the indexing model from the issue text.

Description

documentation enhancement help wanted intermediate

Problem

The README has an "SDK & Client Libraries" section (lines 46-86) with a short snippet for each language, then moves on. An integrator following it hits immediate gaps:

  • How do you attach the JWT? The example passes accessToken in Configuration, but the token has to be refreshed on expiry — and the expiry behaviour is inconsistent between auth services (see the token-expiry issue).
  • How do you paginate? docs/GRAPHQL_GATEWAY.md documents cursor pagination, but nothing explains it for the REST SDKs, and list endpoints are inconsistent (see the shared-query-DTO issue).
  • How do errors surface? The shape is ad hoc and polymorphic (see the problem+json issue).
  • What do rate-limit headers mean? Undocumented (see the rate-limit-headers issue).
  • There is no runnable example. examples/ exists — check what is in it before adding more.

Why it matters

The generated SDKs are the primary integration surface and they are published as CI artifacts. Documentation is what turns a generated client into something a developer can actually use. Without this, every integration question becomes a support ticket or an issue, and the failure modes are all things an integrator will hit on day one.

Suggested Direction

  1. Add docs/SDK_GUIDE.md covering, in order of first need:
    • Authentication: obtaining a token, storing it, refreshing on expiry, and what happens when a refresh fails.
    • Error handling: how errors surface in the generated clients, and the recommended retry policy per status code.
    • Pagination: cursor semantics, with a runnable loop over pages.
    • Rate limits: the header contract and how to throttle politely.
    • Timeouts and retries: recommended client configuration.
    • Webhooks: signature verification, pointing at src/infrastructure/webhooks/services/webhook-hmac.service.ts for the scheme.
  2. Make every example runnable. Prefer snippets that can be executed against a local instance rather than illustrative fragments.
  3. Cross-link rather than duplicate the deep docs: docs/GRAPHQL_GATEWAY.md, docs/JOB_CONTROL_API.md, docs/RBAC.md, docs/WEBSOCKET_SPECIFICATION.md.
  4. Cover both languages, or state clearly that the Python SDK is not yet at parity if that is the case — better to say so than to leave it ambiguous.
  5. Link it from the README SDK section.

Constraints

  • Verify each example against the current code before publishing; stale examples are worse than none.
  • Do not document behaviour that is about to change — if the error format or rate-limit headers are changing under other issues in flight, note that explicitly and link the issue.
  • The token-refresh section depends on the token-expiry issue being resolved, or it will describe ambiguous behaviour.

Acceptance Criteria

  • docs/SDK_GUIDE.md exists and covers auth, errors, pagination, rate limits, and webhooks.
  • Every code example is verified to run against a local instance.
  • Both TypeScript and Python are covered, or the gap is explicitly stated.
  • The guide cross-links the existing docs/ files rather than duplicating them.
  • README.md links to it from the SDK section.
  • Anything in flux is flagged with a link to the relevant issue.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.