@burojs/hasura 0.2.0 → 0.5.0

package/README.md

@@ -56,22 +56,21 @@ registry rather than by branching on resource names:
 | `dataBody` | route a heavy array payload into/out of a 1:1 sibling table |
 | `live` | opt this resource into subscription-driven invalidation |
 
-#### `recoverAuth` fires on HTTP 401 — which is not how Hasura rejects a credential
-
-`config.recoverAuth` is consulted when a request comes back with HTTP **401**,
-and only then. The one capture in this repository of a real Hasura rejection —
-`packages/mock-kit/fixtures/hasura/error-unauthorized.json`, taken from a live
-backend with a deliberately malformed bearer token — came back **HTTP 200 with
-an `invalid-jwt` errors envelope**. Replayed through this provider that
-surfaces as `{ kind: 'protocol', code: 'graphql-error' }`, `recoverAuth` is
-never called, and app logic keyed on `kind: 'auth'` never fires either.
-
-So `recoverAuth` is useful for a deployment that really answers 401 (a proxy or
-gateway in front of Hasura); against Hasura's own rejection shape it is inert.
-The behaviour is pinned by `tests/fixture-fidelity.test.ts`'s
-`error-unauthorized` case, and the package's existing 401-recovery tests use a
-fabricated 401 — they are not evidence about Hasura. Keying recovery on the
-error envelope is a product decision this package has not taken.
+#### Errors Hasura sends with HTTP 200
+
+Hasura answers every GraphQL-level failure with HTTP 200, so the provider
+classifies the envelope by `extensions.code`: `access-denied` and
+`permission-error` reject as `{ kind: 'forbidden', code }`, `invalid-jwt` as
+`{ kind: 'auth', code: 'invalid-jwt' }`, and every other code as
+`{ kind: 'protocol', code: 'graphql-error' }`. When the app passes an
+`authProvider` to `<BuroProvider>`, an `auth` rejection reaches its `onError`,
+which decides whether to refresh; on `refreshed` the runtime replays a read once
+(a mutation once when it is replay-safe). `config.recoverAuth` remains the hook
+for an HTTP **401**, which a proxy or gateway in front of Hasura answers; it is
+not consulted for the envelope. A mutation whose request was sent and got no
+answer at all rejects as `{ kind: 'sent', code: 'hasura-request-sent',
+retryable: false }`: it may have been applied. Pinned by
+`tests/fixture-fidelity.test.ts` and `tests/error-kinds.test.ts`.
 
 Optimistic concurrency is available per call: pass
 `providerOptions.ifUpdatedAt` on an update and the mutation switches to a