@assinafy/sdk 2.2.0 → 2.4.0

package/docs/API_COVERAGE.md

@@ -2,10 +2,11 @@
 
 This ledger maps the official
 [`GET /v1/docs/openapi.json`](https://api.assinafy.com.br/v1/docs/openapi.json)
-contract to the public SDK API: 67 paths, 89 HTTP operations, and 39 component
+contract to the public SDK API: 71 paths, 93 HTTP operations, and 39 component
 schemas.
 
-All paths below include the `/v1` prefix shown by the OpenAPI document. The
+All paths below include the `/v1` prefix shown by the OpenAPI document, except
+the RFC 8615 `.well-known` document, which is served at the host root. The
 SDK's default `baseUrl` already ends in `/v1`, so resource implementations use
 the corresponding relative path without repeating that prefix.
 
@@ -13,7 +14,7 @@ Status meanings:
 
 - **Covered** — a public, typed SDK method sends the operation.
 - **Compatibility extension** — route retained for existing integrations but
-  absent from the current OpenAPI path set and excluded from the 89-operation
+  absent from the current OpenAPI path set and excluded from the 93-operation
   total.
 
 ## Accounts — 10/10
@@ -93,6 +94,21 @@ Status meanings:
 | `POST` | `/v1/accounts/{accountId}/fields/validate-multiple` | `client.fields.validateMultiple(entries, options?)` | Covered |
 | `GET` | `/v1/field-types` | `client.fields.listTypes()` | Covered |
 
+## OAuth — 4/4
+
+Endpoints an OAuth application calls. The token, revocation and userinfo
+operations answer with flat RFC 6749 / OIDC bodies rather than the
+`{ status, message, data }` envelope used everywhere else, and the SDK returns
+them unwrapped. The browser-facing `/oauth/authorize` page belongs to the
+authorization server (`https://auth.assinafy.com.br`), not to this API.
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/.well-known/oauth-protected-resource` | `client.oauth.getProtectedResourceMetadata()` | Covered |
+| `POST` | `/v1/oauth/token` | `client.oauth.exchangeCode(options)` / `client.oauth.refreshToken(options)` | Covered |
+| `POST` | `/v1/oauth/revoke` | `client.oauth.revokeToken(options)` | Covered |
+| `GET` | `/v1/oauth/userinfo` | `client.oauth.getUserInfo(accessToken?)` | Covered |
+
 ## Signers — 5/5
 
 | Method | Path | SDK method | Status |
@@ -171,7 +187,7 @@ Five additional routes are documented separately under
 ## Template compatibility routes
 
 These routes are available to existing integrations but do not appear in the
-current OpenAPI path set. They are excluded from the official 89-operation
+current OpenAPI path set. They are excluded from the official 93-operation
 coverage count.
 
 | Method | Path | SDK method | Status |
@@ -199,6 +215,14 @@ the endpoint count:
 - `client.webhookVerifier` parses webhook envelopes and optionally verifies a
   caller-configured HMAC contract; signature verification itself is not in the
   current OpenAPI document.
+- `client.oauth.getAuthorizationServerMetadata(issuer?)` reads the RFC 8414
+  document published by the authorization server, and
+  `client.oauth.createAuthorizationUrl(options)` /
+  `client.oauth.readAuthorizationCallback(params, expected)` drive the
+  browser-facing half of the flow. Neither host runs on this API, so they add no
+  operations to the count.
+- `ApiError.challenge` exposes the parsed `WWW-Authenticate` header, which names
+  the scope missing from a `403 insufficient_scope`.
 
 For request and response payload definitions, use the exported TypeScript
 interfaces and each method's JSDoc examples together with the

package/docs/COMPATIBILITY.md

@@ -58,6 +58,69 @@ method counters. Notification counters are not mutually exclusive.
 are mutually exclusive and sum to `signature_requests`. Older unsuffixed email
 and WhatsApp counters remain optional.
 
+## OAuth spans two hosts, and sandbox discovery is unreachable
+
+The flow deliberately spans two hosts, which no other part of this SDK does:
+
+```text
+GET   https://api.assinafy.com.br/.well-known/oauth-protected-resource   # host root, NOT /v1
+GET   https://auth.assinafy.com.br/.well-known/oauth-authorization-server
+GET   https://auth.assinafy.com.br/oauth/authorize                       # browser only
+POST  https://api.assinafy.com.br/v1/oauth/token
+POST  https://api.assinafy.com.br/v1/oauth/revoke
+GET   https://api.assinafy.com.br/v1/oauth/userinfo
+```
+
+`getProtectedResourceMetadata()` therefore builds its URL from the configured
+base URL's **origin**, not from `baseUrl` itself, and
+`getAuthorizationServerMetadata()` issues a cross-host request on the
+credential-free transport.
+
+The sandbox has its own authorization server at
+`https://auth-sandbox.assinafy.com.br`, whose `/oauth/authorize` consent screen
+is live. Its discovery documents, however, cannot be fetched: nginx on the
+sandbox hosts rejects **any** path beginning with a dot — `/.anything` answers
+`403` while `/anything` answers `404` — so `/.well-known/…` never reaches the
+application. Skip discovery there by naming the endpoints explicitly; both
+`createAuthorizationUrl` options exist for exactly this case:
+
+```ts
+const client = new AssinafyClient({ baseUrl: 'https://sandbox.assinafy.com.br/v1' });
+
+const request = await client.oauth.createAuthorizationUrl({
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  redirectUri: 'https://myapp.example.com/oauth/callback',
+  scopes: ['documents:read'],
+  issuer: 'https://auth-sandbox.assinafy.com.br',
+  authorizationEndpoint: 'https://auth-sandbox.assinafy.com.br/oauth/authorize',
+});
+```
+
+The token, revocation and userinfo endpoints are resolved against the
+configured `baseUrl`, so they follow whichever host the client points at.
+Confirm the sandbox deployment exposes them before running the exchange leg
+there: at the time of writing its OpenAPI document publishes 67 paths and does
+not list `/v1/oauth/…`, while production publishes 71 and does. A `404` from
+this API is byte-identical for a bad id and for a route that does not exist, so
+it is never on its own proof that a route is missing.
+
+Response shapes diverge from the rest of the API on purpose:
+
+| Operation | Success body | Error body |
+| --- | --- | --- |
+| Discovery documents | bare metadata object (RFC 8615) | — |
+| `POST /oauth/token`, `POST /oauth/revoke` | flat, no envelope (RFC 6749 §5.1) | flat `{ error, error_description }` (§5.2) |
+| `GET /oauth/userinfo` | flat claims object (OIDC Core §5.3.2) | the usual `{ status, message, data }` envelope |
+
+Both JSON and `application/x-www-form-urlencoded` bodies are accepted by the
+token and revocation endpoints; the SDK sends JSON because that is what the
+published `requestBody` documents.
+
+The RFC 8707 `resource` indicator defaults to the configured API origin, and is
+omitted when that origin is a loopback `http://` host — the shape used by mock
+servers and the packed-consumer smoke test, which has no valid resource
+identifier.
+
 ## List pagination
 
 Two behaviours of the list endpoints are silent rather than loud, so neither

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@assinafy/sdk",
-    "version": "2.2.0",
+    "version": "2.4.0",
     "packageManager": "bun@1.4.0",
     "description": "TypeScript SDK for Assinafy API - Digital signature platform",
     "type": "commonjs",
@@ -87,6 +87,7 @@
         "dist",
         "docs",
         "README.md",
+        "README.en.md",
         "CHANGELOG.md",
         "SECURITY.md",
         "LICENSE"