@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/{api → reference/management-api}/authorization-and-scopes.md

@@ -1,14 +1,18 @@
 ---
+type: reference
 layout: docs
 ---
 
 # Authorization and scopes
 
-The Picked API uses a scope-based authorization model. Every authenticated caller (session user or API key) carries a set of scopes that determine which operations they can perform. This guide explains the scope system, roles, and how permissions are resolved.
+The Picked API controls access with scopes. Every authenticated caller carries a set
+of scopes, and those scopes decide which operations the caller can do. A caller is
+either a user with a session or an API key. This guide covers the scopes, the roles,
+and how the API resolves a permission.
 
-## Scope naming format
+## The format of a scope name
 
-Scopes follow the `entity/action` convention:
+A scope has the form `resource/action`:
 
 ```
 organization/read
@@ -16,83 +20,87 @@ organization_members/create
 organization_projects/delete
 ```
 
-- **entity** — a lowercase name using underscores for multi-word entities (e.g., `organization_members`, `organization_api_keys`)
-- **action** — one of `create`, `read`, `update`, or `delete`
+- **resource** — a lowercase name. It uses an underscore between words, as in
+  `organization_members` and `organization_api_keys`.
+- **action** — one of `create`, `read`, `update`, or `delete`.
 
-In the GraphQL schema, scopes are represented as the `Scope` enum using uppercase with underscores (e.g., `ORGANIZATION_READ`, `ORGANIZATION_MEMBERS_CREATE`). Both formats refer to the same scope.
+The GraphQL schema holds the scopes in the `Scope` enum. There they are uppercase
+with an underscore between words, as in `ORGANIZATION_READ` and
+`ORGANIZATION_MEMBERS_CREATE`. The two forms name the same scope.
 
 ## Full scope list
 
-The following scopes are available:
+These are the scopes:
 
 ### Organization
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization/create` | `ORGANIZATION_CREATE` | Create new organizations |
-| `organization/read` | `ORGANIZATION_READ` | View organization details |
-| `organization/update` | `ORGANIZATION_UPDATE` | Update organization name, slug, and settings |
+| `organization/create` | `ORGANIZATION_CREATE` | Create an organization |
+| `organization/read` | `ORGANIZATION_READ` | Read the detail of an organization |
+| `organization/update` | `ORGANIZATION_UPDATE` | Update the name, the slug, and the settings of an organization |
 | `organization/delete` | `ORGANIZATION_DELETE` | Delete an organization |
 
 ### Organization members
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add members to an organization |
-| `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | View organization member list |
-| `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update member roles |
-| `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove members from an organization |
+| `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add a member to an organization |
+| `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | Read the member list of an organization |
+| `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update the role of a member |
+| `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove a member from an organization |
 
 ### Organization invitations
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send invitations to join an organization |
-| `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | View pending invitations |
-| `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke pending invitations |
+| `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send an invitation to join an organization |
+| `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | Read the invitations that wait for an answer |
+| `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke an invitation that waits for an answer |
 
 ### Organization projects
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create new projects |
-| `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | View project details |
-| `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update project settings |
-| `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete projects |
+| `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create a project |
+| `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | Read the detail of a project |
+| `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update the settings of a project |
+| `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete a project |
 
 ### Organization API keys
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create new API keys |
-| `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | View API keys (prefix only, not the full key) |
-| `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke API keys |
+| `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create an API key |
+| `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | Read the API keys. This gives the prefix only, and not the full key. |
+| `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke an API key |
 
 ### Organization integrations
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up new integrations |
-| `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | View integration configurations |
-| `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Modify integration settings |
-| `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove integrations |
+| `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up an integration |
+| `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | Read the options of an integration |
+| `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Change the settings of an integration |
+| `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove an integration |
 
 ### Organization reports
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create new reports |
-| `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | View reports |
-| `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update report settings |
-| `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete reports |
+| `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create a report |
+| `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | Read a report |
+| `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update the settings of a report |
+| `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete a report |
 
 ## Roles
 
-Organization members are assigned one of two roles:
+Each member of an organization holds one of two roles:
 
 ### Owner
 
-Owners have full control within their organization. Their default scopes include:
+An owner has full control inside the organization. These are the default scopes of an
+owner:
 
 - All `organization/*` scopes (`read`, `update`, `delete`)
 - All `organization_members/*` scopes
@@ -104,7 +112,8 @@ Owners have full control within their organization. Their default scopes include
 
 ### Member
 
-Members have broad access but cannot delete the organization or manage other members. Their default scopes include:
+A member can reach most things, but cannot delete the organization and cannot control
+another member. These are the default scopes of a member:
 
 - `organization/read`, `organization/update`
 - `organization_members/read`
@@ -114,7 +123,7 @@ Members have broad access but cannot delete the organization or manage other mem
 - All `organization_integrations/*` scopes
 - `organization_reports/read`
 
-The key differences between owner and member:
+These are the differences between an owner and a member:
 
 | Capability | Owner | Member |
 |-----------|-------|--------|
@@ -123,24 +132,30 @@ The key differences between owner and member:
 | Remove members | Yes | No |
 | Update member roles | Yes | No |
 | Revoke invitations | Yes | No |
-| Manage projects and integrations | Yes | Yes |
-| Manage API keys | Yes | Yes |
-| View reports | Yes | Yes |
+| Control projects and integrations | Yes | Yes |
+| Control API keys | Yes | Yes |
+| Read reports | Yes | Yes |
 
 ## How scopes are resolved
 
-When an authenticated request reaches the API, the authorization system resolves scopes as follows:
+When an authenticated request reaches the API, the API resolves the scopes like this:
 
-1. **Session-authenticated users** — the API looks up the caller's role within the target organization and assigns the default scopes for that role.
-2. **API key requests** — the API uses the scopes that were assigned to the key at creation time. These scopes are always a subset of the creating user's scopes.
+1. **A user with a session** — the API finds the role of that caller in the target
+   organization. It then gives the caller the default scopes of that role.
+2. **A request with an API key** — the API uses the scopes that the key received when
+   somebody created it. Those scopes are always scopes of the user who created the
+   key.
 
-For operations that target a specific organization (most queries and mutations), the caller must have the required scope within that organization. For root-level operations like `organizationCreate`, the scope is resolved at the account level.
+Most queries and mutations point at one organization. For those, the caller must hold
+the scope inside that organization. For a root-level operation such as
+`organizationCreate`, the API resolves the scope at the account level.
 
-If the caller lacks the required scope, the API returns an authorization error with a `FORBIDDEN` code. See [Error Handling](./error-handling.md) for details.
+When the caller does not hold the scope that an operation needs, the API returns an
+authorization error with the code `FORBIDDEN`. See [Errors](/reference/management-api/error-handling).
 
 ## Operations and required scopes
 
-The following table maps common operations to the scopes they require:
+This table gives the scope that each common operation needs:
 
 ### Queries
 
@@ -192,7 +207,7 @@ Some mutations do not require organization-level scopes because they operate on
 | `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
 | `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
 
-## Querying scopes
+## Read your scopes
 
 ### Root-level scopes
 
@@ -259,4 +274,12 @@ Response:
 }
 ```
 
-This is useful for building UIs that adapt based on the caller's permissions — for example, hiding a "Delete Organization" button when the caller lacks `ORGANIZATION_DELETE`.
+Use this to build a UI that changes with the permissions of the caller. An example is
+a **Delete Organization** button that the UI hides when the caller does not hold
+`ORGANIZATION_DELETE`.
+
+## Related
+
+- [Authentication](/reference/management-api/authentication)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
+- [API keys](/reference/dashboard/api-keys) — the dashboard surface.

package/dist/docs/reference/management-api/error-handling.md

@@ -0,0 +1,233 @@
+---
+type: reference
+layout: docs
+---
+
+# Errors
+
+The Picked API returns an error in the standard GraphQL format. This guide covers the
+shape of an error response, every error code, and what your code must do with each
+one.
+
+## Error response shape
+
+When an operation fails, the API returns an `errors` array in the response body. Each
+error object holds these fields:
+
+```json
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "A human-readable description of the error",
+      "path": ["mutationName"],
+      "extensions": {
+        "code": "ERROR_CODE"
+      }
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `message` | A description of the error that a person can read. Put it in your log. Do not write code against it. |
+| `path` | The path to the field in the query that made the error. |
+| `extensions.code` | An error code that a machine can read. Write your code against this field. |
+
+One response can hold more than one error. The `data` field is `null` when the whole
+operation failed. It holds part of the data when only some fields failed.
+
+## Authentication error codes
+
+These errors come from a session, an account, OAuth, a magic link, a password
+operation, or MFA. They match the `AuthErrorCode` enum in the schema.
+
+| Code | Description |
+|------|-------------|
+| `INVALID_CREDENTIALS` | The email address and the password do not match. |
+| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#verify-an-email-address). |
+| `USER_NOT_FOUND` | There is no account with that email address. |
+| `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
+| `WEAK_PASSWORD` | The password is not strong enough. |
+| `INVALID_TOKEN` | The token is invalid or malformed. This covers a verification token, a reset token, and a magic link token. |
+| `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
+| `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
+| `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
+| `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
+| `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
+
+### Example: invalid credentials
+
+```json
+{
+  "data": {
+    "sessionCreate": {
+      "session": null,
+      "requiresMfa": false,
+      "mfaFactors": null
+    }
+  },
+  "errors": [
+    {
+      "message": "Invalid credentials",
+      "path": ["sessionCreate"],
+      "extensions": {
+        "code": "INVALID_CREDENTIALS"
+      }
+    }
+  ]
+}
+```
+
+## Authorization error codes
+
+An authorization error happens when the caller does not hold the
+[scope](/reference/management-api/authorization-and-scopes) that an operation needs.
+
+| Code | Description |
+|------|-------------|
+| `UNAUTHORIZED` | The request carries no valid authentication. It has no `Authorization` header and no `x-api-key` header, or the token is invalid. |
+| `FORBIDDEN` | The caller is authenticated, but it does not hold the scope that the operation needs. |
+
+### Example: the scope is not enough
+
+A caller that holds `organization/read` only tries to delete an organization. It
+receives this:
+
+```json
+{
+  "data": {
+    "organizationDelete": null
+  },
+  "errors": [
+    {
+      "message": "Insufficient permissions",
+      "path": ["organizationDelete"],
+      "extensions": {
+        "code": "FORBIDDEN"
+      }
+    }
+  ]
+}
+```
+
+## Organization, member, and invitation error codes
+
+These errors come from an organization, a member operation, or an invitation. They
+match the `ErrorCode` enum in the schema.
+
+### Organization errors
+
+| Code | Description |
+|------|-------------|
+| `ORGANIZATION_NOT_FOUND` | That organization is not there, or the caller cannot reach it. |
+| `ORGANIZATION_ALREADY_EXISTS` | An organization with that name is there already. |
+| `SLUG_ALREADY_EXISTS` | Another organization uses that slug already. |
+| `INVALID_SLUG` | The slug holds an invalid character. A slug takes lowercase letters, digits, and hyphens only. |
+
+### Member errors
+
+| Code | Description |
+|------|-------------|
+| `MEMBER_NOT_FOUND` | That user is not a member of the organization. |
+| `MEMBER_ALREADY_EXISTS` | The user is a member of the organization already. |
+| `CANNOT_REMOVE_PRIMARY_OWNER` | You cannot remove the primary owner of an organization. |
+| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change the role of that same member. Another owner must do it. |
+
+### Invitation errors
+
+| Code | Description |
+|------|-------------|
+| `INVITATION_NOT_FOUND` | That invitation is not there. |
+| `INVITATION_EXPIRED` | The invitation expired. Nobody can accept it now. |
+| `INVITATION_ALREADY_ACCEPTED` | Somebody accepted the invitation already. |
+
+### Project errors
+
+| Code | Description |
+|------|-------------|
+| `PROJECT_NOT_FOUND` | That project is not there, or the caller cannot reach it. |
+
+### General errors
+
+| Code | Description |
+|------|-------------|
+| `VALIDATION_ERROR` | The input failed a validation rule. Read the `message` field to learn which field is invalid. |
+| `INTERNAL_ERROR` | The server met an unexpected error. Try the request again. Contact support when the error continues. |
+
+## What your code must do
+
+### Look for an error first
+
+Check every response for an `errors` array before you read `data`:
+
+```javascript
+const response = await fetch('/graphql', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${accessToken}`,
+  },
+  body: JSON.stringify({ query, variables }),
+});
+
+const result = await response.json();
+
+if (result.errors) {
+  for (const error of result.errors) {
+    const code = error.extensions?.code;
+
+    switch (code) {
+      case 'UNAUTHORIZED':
+        // Send the user to the sign-in page.
+        break;
+      case 'FORBIDDEN':
+        // Show a permissions error.
+        break;
+      case 'RATE_LIMITED':
+        // Wait, then try again.
+        break;
+      default:
+        // Put the message in the log, or show it.
+        console.error(error.message);
+    }
+  }
+}
+```
+
+### Refresh a token that expired
+
+A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
+[session refresh](/reference/management-api/authentication#refresh-a-session) first. Do not treat it as a
+failure to sign in:
+
+```javascript
+if (code === 'UNAUTHORIZED' && refreshToken) {
+  const refreshResult = await sessionRefresh(refreshToken);
+  if (refreshResult.session) {
+    // Try the first request again with the new access token.
+  } else {
+    // Send the user to the sign-in page.
+  }
+}
+```
+
+### Read data that is only part complete
+
+GraphQL can return part of the data together with an error. Take a query that reads
+an organization and its members. It can succeed for the organization and fail for the
+members, when the caller does not hold `organization_members/read`. The response then
+holds `data` with the organization, and `errors` for the members field. Always read
+both.
+
+### Try again after a transient failure
+
+`INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
+exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
+usually enough.
+
+## Related
+
+- [Authentication](/reference/management-api/authentication)
+- [Your first API call](/tutorials/first-api-call)

package/dist/docs/{api → reference/management-api}/pagination.md

@@ -1,14 +1,17 @@
 ---
+type: reference
 layout: docs
 ---
 
 # Pagination
 
-The Picked API uses Relay-style cursor-based pagination for all list fields that may return large result sets. This guide explains the connection pattern and demonstrates how to paginate through results.
+The Picked API paginates every list field that can return a large result. It uses a
+cursor, in the Relay-style pattern. This guide covers the connection pattern and
+shows how to move through a result.
 
 ## Connection pattern
 
-Paginated fields return a **connection** object with the following shape:
+A paginated field returns a **connection** object with this shape:
 
 ```graphql
 type ExampleConnection {
@@ -32,20 +35,21 @@ type PageInfo {
 
 | Field | Description |
 |-------|-------------|
-| `edges` | An ordered list of edges, each containing a `cursor` and a `node` (the actual data object) |
-| `pageInfo.hasNextPage` | `true` if more results exist after the last edge |
-| `pageInfo.hasPreviousPage` | `true` if results exist before the first edge |
-| `pageInfo.startCursor` | Cursor of the first edge in the current page |
-| `pageInfo.endCursor` | Cursor of the last edge in the current page |
-| `totalCount` | Total number of items across all pages |
+| `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
+| `pageInfo.hasNextPage` | `true` when more results come after the last edge |
+| `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
+| `pageInfo.startCursor` | The cursor of the first edge on the current page |
+| `pageInfo.endCursor` | The cursor of the last edge on the current page |
+| `totalCount` | The number of items on every page together |
 
 ## Forward pagination with `first` and `after`
 
-To paginate forward through results, use the `first` argument to specify the page size and the `after` argument to specify the cursor to start after.
+To move forward through the results, use two arguments. The `first` argument gives
+the page size. The `after` argument gives the cursor to start after.
 
 ### First page
 
-Omit the `after` argument to fetch the first page:
+Leave the `after` argument out to read the first page:
 
 ```graphql
 query {
@@ -89,16 +93,17 @@ query {
 }
 ```
 
-## Checking for more pages
+## Check for more pages
 
-Before requesting the next page, check the `hasNextPage` field:
+Read the `hasNextPage` field before you ask for the next page:
 
-- `hasNextPage: true` — more results are available; pass `endCursor` to the next request's `after` argument
-- `hasNextPage: false` — all results have been fetched; stop paginating
+- `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
+  argument of the next request.
+- `hasNextPage: false` — you read every result. Stop here.
 
 ## Full paginated query example
 
-The following example fetches all members of an organization, page by page:
+This example reads every member of an organization, one page at a time:
 
 ```graphql
 # Page 1
@@ -154,7 +159,8 @@ Continue until `hasNextPage` returns `false`.
 
 ## Paginated fields
 
-The following fields in the schema return connection types and support `first`/`after` pagination:
+These fields in the schema return a connection type. They all take the `first` and
+`after` arguments:
 
 | Parent Type | Field | Connection Type |
 |------------|-------|----------------|
@@ -170,7 +176,17 @@ All of these fields accept the same `first` and `after` arguments and return the
 
 ## Tips
 
-- **Default page size** — if `first` is omitted, the API applies a default limit. Explicitly setting `first` ensures predictable page sizes.
-- **Cursors are opaque** — cursor strings should be treated as opaque tokens. Do not parse, construct, or modify them. Pass them exactly as received from the API.
-- **Stable ordering** — results within a connection are returned in a stable order. The same cursor always refers to the same position in the result set.
-- **Combine with other fields** — pagination arguments can be used alongside other query fields. For example, fetching an organization and its first page of members in a single request is common and efficient.
+- **The default page size** — the API applies a default limit when you leave `first`
+  out. Set `first` yourself to make sure that each page has the size you expect.
+- **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
+  build it, or change it. Pass it back exactly as the API gave it.
+- **The order is stable** — a connection returns its results in a stable order. The
+  same cursor always points at the same position in the result.
+- **Use them with other fields** — you can use the pagination arguments together with
+  other query fields. One request that reads an organization and the first page of
+  its members is common, and it is efficient.
+
+## Related
+
+- [Your first API call](/tutorials/first-api-call)
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes)