@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.2

package/dist/docs/reference/management-api/authentication.md

@@ -1,74 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Authentication
-
-The Picked API supports four ways to authenticate. They are a session from an email
-address and a password, an OAuth provider, a magic link, and an API key. This guide
-covers each one. It also covers how to control a session and how to use multi-factor
-authentication (MFA).
-
-## Use a session
-
-After the caller has a session, it puts the access token in the `Authorization`
-header of every request that needs authentication:
-
-```
-Authorization: Bearer <accessToken>
-```
-
-The `expiresAt` field of the session gives the time at which the access token
-expires. The caller must refresh the session before that time.
-
-### Authenticator assurance levels
-
-The session holds an `aal` field, and it gives the strength of the authentication:
-
-| Level | Meaning |
-|-------|---------|
-| `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
-| `AAL2` | More than one factor: the user completed an MFA challenge |
-
-Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
-returns an authorization error.
-
-## The mutations
-
-| Mutation | What it does |
-| --- | --- |
-| `sessionCreate` | Authenticates an email address and a password. Returns a session, or `requiresMfa`. |
-| `sessionRefresh` | Exchanges a refresh token for a new session. Needs no `Authorization` header. |
-| `accountCreate` | Creates an account. `metadata` takes any JSON. |
-| `accountVerifyEmail` | Completes email verification with the token from the email. |
-| `accountResendVerification` | Sends the verification email again. |
-| `oauthAuthorize` | Returns the authorization URL for a provider. Google is supported. |
-| `oauthCallback` | Exchanges an OAuth code for a session. |
-| `magicLinkSend` | Sends a sign-in link to an email address. |
-| `magicLinkVerify` | Exchanges a magic-link token for a session. |
-| `passwordResetSend` | Sends a password reset email. |
-| `passwordReset` | Completes a reset with the token from the email. |
-| `passwordUpdate` | Changes a password. Needs authentication. |
-| `mfaFactorEnroll` | Adds an MFA factor. A new factor is `UNVERIFIED`. |
-| `mfaChallengeSend` | Sends a code to the telephone number of the factor. |
-| `mfaChallengeVerify` | Verifies a challenge. Moves the session to `AAL2`. |
-| `mfaFactorUnenroll` | Removes an MFA factor. |
-| `apiKeyCreate` | Creates an API key. Only a user with a session can call it. |
-| `apiKeyRevoke` | Invalidates a key immediately. |
-
-## Credentials
-
-| Credential | Header |
-| --- | --- |
-| Session access token | `Authorization: Bearer <accessToken>` |
-| API key | `x-api-key: pk_live_abc123...` |
-
-## Related
-
-- [How to authenticate with a password](/how-to/authenticate-with-a-password)
-- [How to authenticate with OAuth](/how-to/authenticate-with-oauth)
-- [How to authenticate with a magic link](/how-to/authenticate-with-a-magic-link)
-- [How to set up MFA](/how-to/set-up-mfa)
-- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
-- [Authorization and scopes](/reference/management-api/authorization-and-scopes)

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

@@ -1,285 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Authorization and scopes
-
-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.
-
-## The format of a scope name
-
-A scope has the form `resource/action`:
-
-```
-organization/read
-organization_members/create
-organization_projects/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`.
-
-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
-
-These are the scopes:
-
-### Organization
-
-| Scope | GraphQL Enum | Description |
-|-------|-------------|-------------|
-| `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 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 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 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 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 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 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
-
-Each member of an organization holds one of two roles:
-
-### Owner
-
-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
-- All `organization_invitations/*` scopes
-- `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
-- All `organization_api_keys/*` scopes
-- All `organization_integrations/*` scopes
-- `organization_reports/read`
-
-### Member
-
-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`
-- `organization_invitations/read`
-- `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
-- All `organization_api_keys/*` scopes
-- All `organization_integrations/*` scopes
-- `organization_reports/read`
-
-These are the differences between an owner and a member:
-
-| Capability | Owner | Member |
-|-----------|-------|--------|
-| Delete the organization | Yes | No |
-| Invite new members | Yes | No |
-| Remove members | Yes | No |
-| Update member roles | Yes | No |
-| Revoke invitations | Yes | No |
-| 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 API resolves the scopes like this:
-
-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.
-
-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.
-
-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
-
-This table gives the scope that each common operation needs:
-
-### Queries
-
-| Query | Required Scope |
-|-------|---------------|
-| `organization` | `organization/read` |
-| `organizations` | `organization/read` |
-| `project` | `organization_projects/read` |
-| `apiKeys` | `organization_api_keys/read` |
-| `shopifyWebhooks` | `organization_integrations/read` |
-| `shopifyMetafieldConfigs` | `organization_integrations/read` |
-| `shopifyProduct` / `shopifyProducts` | `organization_integrations/read` |
-| `report` | `organization_reports/read` |
-
-### Mutations
-
-| Mutation | Required Scope |
-|----------|---------------|
-| `organizationCreate` | `organization/create` |
-| `organizationUpdate` | `organization/update` |
-| `organizationDelete` | `organization/delete` |
-| `organizationMemberInvite` | `organization_invitations/create` |
-| `organizationInvitationRevoke` | `organization_invitations/delete` |
-| `organizationMemberRemove` | `organization_members/delete` |
-| `organizationMemberRoleUpdate` | `organization_members/update` |
-| `projectCreate` | `organization_projects/create` |
-| `apiKeyCreate` | `organization_api_keys/create` |
-| `apiKeyRevoke` | `organization_api_keys/delete` |
-| `shopifyWebhookCreate` | `organization_integrations/create` |
-| `shopifyWebhookUpdate` | `organization_integrations/update` |
-| `shopifyWebhookDelete` | `organization_integrations/delete` |
-| `shopifyMetafieldConfigCreate` | `organization_integrations/create` |
-| `shopifyMetafieldConfigUpdate` | `organization_integrations/update` |
-| `shopifyMetafieldConfigDelete` | `organization_integrations/delete` |
-| `reportCreate` | `organization_reports/create` |
-| `reportUpdate` | `organization_reports/update` |
-| `reportDelete` | `organization_reports/delete` |
-
-Some mutations do not require organization-level scopes because they operate on the caller's own data:
-
-| Mutation | Requirement |
-|----------|------------|
-| `sessionCreate` / `sessionRefresh` | No authentication required |
-| `accountCreate` / `accountVerifyEmail` | No authentication required |
-| `oauthAuthorize` / `oauthCallback` | No authentication required |
-| `magicLinkSend` / `magicLinkVerify` | No authentication required |
-| `passwordResetSend` / `passwordReset` | No authentication required |
-| `passwordUpdate` | Authenticated session (no specific scope) |
-| `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
-| `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
-
-## Read your scopes
-
-### Root-level scopes
-
-The `viewerScopes` query returns the root-level scopes for the authenticated caller:
-
-```graphql
-query {
-  viewerScopes
-}
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "viewerScopes": [
-      "ORGANIZATION_CREATE"
-    ]
-  }
-}
-```
-
-### Organization-level scopes
-
-Each `Organization` object exposes a `viewerScopes` field that returns the scopes the caller has within that specific organization:
-
-```graphql
-query {
-  organization(input: { slug: "my-company" }) {
-    id
-    name
-    viewerScopes
-  }
-}
-```
-
-Response:
-
-```json
-{
-  "data": {
-    "organization": {
-      "id": "org_abc123",
-      "name": "My Company",
-      "viewerScopes": [
-        "ORGANIZATION_READ",
-        "ORGANIZATION_UPDATE",
-        "ORGANIZATION_MEMBERS_READ",
-        "ORGANIZATION_PROJECTS_READ",
-        "ORGANIZATION_PROJECTS_UPDATE",
-        "ORGANIZATION_PROJECTS_DELETE",
-        "ORGANIZATION_API_KEYS_CREATE",
-        "ORGANIZATION_API_KEYS_READ",
-        "ORGANIZATION_API_KEYS_DELETE",
-        "ORGANIZATION_INTEGRATIONS_CREATE",
-        "ORGANIZATION_INTEGRATIONS_READ",
-        "ORGANIZATION_INTEGRATIONS_UPDATE",
-        "ORGANIZATION_INTEGRATIONS_DELETE",
-        "ORGANIZATION_REPORTS_READ"
-      ]
-    }
-  }
-}
-```
-
-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

@@ -1,233 +0,0 @@
----
-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#the-mutations). |
-| `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#the-mutations) 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)