@picked/client 0.0.1-dev.1777616114652 → 0.0.1-dev.1777867216429

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

@@ -0,0 +1,262 @@
+---
+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.
+
+## Scope naming format
+
+Scopes follow the `entity/action` convention:
+
+```
+organization/read
+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`
+
+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.
+
+## Full scope list
+
+The following scopes are available:
+
+### 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/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 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 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 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 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 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 |
+
+## Roles
+
+Organization members are assigned one of two roles:
+
+### Owner
+
+Owners have full control within their organization. Their default scopes include:
+
+- 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
+
+Members have broad access but cannot delete the organization or manage other members. Their default scopes include:
+
+- `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`
+
+The key differences between owner and 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 |
+| Manage projects and integrations | Yes | Yes |
+| Manage API keys | Yes | Yes |
+| View reports | Yes | Yes |
+
+## How scopes are resolved
+
+When an authenticated request reaches the API, the authorization system resolves scopes as follows:
+
+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.
+
+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.
+
+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.
+
+## Operations and required scopes
+
+The following table maps common operations to the scopes they require:
+
+### 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) |
+
+## Querying 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"
+      ]
+    }
+  }
+}
+```
+
+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`.

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

@@ -0,0 +1,211 @@
+---
+layout: docs
+---
+
+# Error handling
+
+The Picked API returns errors using the standard GraphQL error format. This guide covers the error response shape, all error codes, and practical strategies for handling errors.
+
+## Error response shape
+
+When an operation fails, the API returns an `errors` array in the response body. Each error object contains:
+
+```json
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "A human-readable description of the error",
+      "path": ["mutationName"],
+      "extensions": {
+        "code": "ERROR_CODE"
+      }
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `message` | A human-readable error description. Suitable for logging but not for programmatic handling. |
+| `path` | The path to the field in the query that caused the error. |
+| `extensions.code` | A machine-readable error code. Use this for programmatic error handling. |
+
+Multiple errors may appear in a single response. The `data` field may be `null` if the entire operation failed, or it may contain partial data if only some fields failed.
+
+## Authentication error codes
+
+These errors relate to session creation, account management, OAuth, magic links, password operations, and MFA. They map to the `AuthErrorCode` enum in the schema.
+
+| Code | Description |
+|------|-------------|
+| `INVALID_CREDENTIALS` | The email/password combination is incorrect. |
+| `EMAIL_NOT_CONFIRMED` | The account exists but the email address has not been verified. See [Authentication](/api/authentication#email-verification). |
+| `USER_NOT_FOUND` | No account exists with the provided email address. |
+| `USER_ALREADY_EXISTS` | An account with this email already exists. Returned during account creation. |
+| `WEAK_PASSWORD` | The provided password does not meet strength requirements. |
+| `INVALID_TOKEN` | The token (verification, reset, or magic link) is invalid or malformed. |
+| `TOKEN_EXPIRED` | The token has expired. The caller should request a new one. |
+| `MFA_CHALLENGE_FAILED` | The MFA verification code is incorrect. |
+| `MFA_FACTOR_NOT_FOUND` | The specified MFA factor does not exist or does not belong to the caller. |
+| `OAUTH_PROVIDER_ERROR` | An error occurred communicating with the OAuth provider (e.g., Google). |
+| `RATE_LIMITED` | Too many requests in a short period. The caller should wait and retry. |
+
+### 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
+
+Authorization errors occur when the caller lacks the required [scope](./authorization-and-scopes.md) for an operation.
+
+| Code | Description |
+|------|-------------|
+| `UNAUTHORIZED` | No valid authentication was provided. The request is missing the `Authorization` header or the `x-api-key` header, or the token/key is invalid. |
+| `FORBIDDEN` | The caller is authenticated but does not have the required scope for the operation. |
+
+### Example: insufficient scope
+
+A caller with only `organization/read` attempting to delete an organization receives:
+
+```json
+{
+  "data": {
+    "organizationDelete": null
+  },
+  "errors": [
+    {
+      "message": "Insufficient permissions",
+      "path": ["organizationDelete"],
+      "extensions": {
+        "code": "FORBIDDEN"
+      }
+    }
+  ]
+}
+```
+
+## Organization, member, and invitation error codes
+
+These errors relate to organization management, member operations, and invitation workflows. They map to the `ErrorCode` enum in the schema.
+
+### Organization errors
+
+| Code | Description |
+|------|-------------|
+| `ORGANIZATION_NOT_FOUND` | The specified organization does not exist or the caller does not have access to it. |
+| `ORGANIZATION_ALREADY_EXISTS` | An organization with this name already exists. |
+| `SLUG_ALREADY_EXISTS` | The requested slug is already in use by another organization. |
+| `INVALID_SLUG` | The slug contains invalid characters. Slugs must be lowercase alphanumeric with hyphens. |
+
+### Member errors
+
+| Code | Description |
+|------|-------------|
+| `MEMBER_NOT_FOUND` | The specified user is not a member of the organization. |
+| `MEMBER_ALREADY_EXISTS` | The user is already a member of the organization. |
+| `CANNOT_REMOVE_PRIMARY_OWNER` | The primary owner of an organization cannot be removed. |
+| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change their own role. Another owner must perform this action. |
+
+### Invitation errors
+
+| Code | Description |
+|------|-------------|
+| `INVITATION_NOT_FOUND` | The specified invitation does not exist. |
+| `INVITATION_EXPIRED` | The invitation has expired and can no longer be accepted. |
+| `INVITATION_ALREADY_ACCEPTED` | The invitation has already been accepted. |
+
+### Project errors
+
+| Code | Description |
+|------|-------------|
+| `PROJECT_NOT_FOUND` | The specified project does not exist or the caller does not have access. |
+
+### General errors
+
+| Code | Description |
+|------|-------------|
+| `VALIDATION_ERROR` | The input failed validation. Check the `message` field for details about which field is invalid. |
+| `INTERNAL_ERROR` | An unexpected server error occurred. Retry the request or contact support if the issue persists. |
+
+## Handling errors in practice
+
+### Check for errors first
+
+Every response should be checked for the presence of an `errors` array before processing `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':
+        // Redirect to login
+        break;
+      case 'FORBIDDEN':
+        // Show a permissions error
+        break;
+      case 'RATE_LIMITED':
+        // Wait and retry
+        break;
+      default:
+        // Log or display the error message
+        console.error(error.message);
+    }
+  }
+}
+```
+
+### Refresh expired tokens
+
+If a request returns `UNAUTHORIZED` and the caller has a refresh token, attempt a [session refresh](/api/authentication#session-refresh) before treating it as a login failure:
+
+```javascript
+if (code === 'UNAUTHORIZED' && refreshToken) {
+  const refreshResult = await sessionRefresh(refreshToken);
+  if (refreshResult.session) {
+    // Retry the original request with the new access token
+  } else {
+    // Redirect to login
+  }
+}
+```
+
+### Handle partial data
+
+GraphQL can return partial data alongside errors. For example, a query that fetches an organization and its members might succeed for the organization but fail for the members if the caller lacks `organization_members/read`. In this case, the response contains both `data` (with the organization) and `errors` (for the members field). Always check both.
+
+### Retry transient failures
+
+`INTERNAL_ERROR` and `RATE_LIMITED` are transient. For `RATE_LIMITED`, implement exponential backoff before retrying. For `INTERNAL_ERROR`, a single retry is usually sufficient.

package/dist/docs/api/index.md

@@ -2,31 +2,192 @@
 layout: docs
 ---
 
-# API
+# Getting started
 
-The Picked API is a GraphQL API that provides programmatic access to all platform features.
+This guide walks you through your first interactions with the Picked GraphQL API, from sending a simple ping to making authenticated queries and mutations.
 
 ## Playground
 
-Explore the API and run queries interactively using the [GraphQL Playground](https://api.picked.app/api/graphql).
+Explore the API and run queries interactively in the [GraphQL Playground](https://api.picked.app/api/graphql).
 
-## Authentication
+## API endpoint
 
-Authenticate requests by including an API key in the `Authorization` header.
+All requests go to a single endpoint:
 
 ```
-Authorization: Bearer your-api-key
+POST https://api.picked.app/api/graphql
 ```
 
-See [API Keys](/api-keys) for how to create and manage keys.
+Every request must use the `POST` method with a JSON body containing a `query` field and an optional `variables` field:
 
-## Making requests
+```json
+{
+  "query": "query { ... }",
+  "variables": { }
+}
+```
 
-Send a POST request to the GraphQL endpoint with your query in the request body.
+Set the `Content-Type` header to `application/json` on every request.
 
 ```bash
 curl -X POST https://api.picked.app/api/graphql \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer your-api-key" \
-  -d '{"query": "{ viewer { id email } }"}'
+  -d '{"query": "{ ping }"}'
+```
+
+## Ping the API
+
+Verify that the API is reachable with the `ping` query. This query does not require authentication.
+
+```graphql
+query {
+  ping
+}
+```
+
+Response:
+
+```json
+{
+  "data": {
+    "ping": "pong"
+  }
+}
+```
+
+If you receive this response, the API is up and ready.
+
+## Authenticate
+
+Most operations require an access token. You obtain one by creating a session with your email and password.
+
+```graphql
+mutation {
+  sessionCreate(input: {
+    email: "you@example.com"
+    password: "your-password"
+  }) {
+    session {
+      accessToken
+      refreshToken
+      expiresAt
+    }
+    requiresMfa
+  }
+}
+```
+
+A successful response returns a `Session` containing an `accessToken` and a `refreshToken`:
+
+```json
+{
+  "data": {
+    "sessionCreate": {
+      "session": {
+        "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+        "refreshToken": "v1.refresh-token...",
+        "expiresAt": "2025-01-15T12:00:00Z"
+      },
+      "requiresMfa": false
+    }
+  }
+}
+```
+
+If `requiresMfa` is `true`, you need to complete the MFA challenge before receiving a session. See the [Authentication](./authentication.md) guide for details.
+
+For server-to-server integrations, prefer [API key authentication](/api/authentication#api-key-authentication) over session tokens.
+
+## Make an authenticated query
+
+Pass the access token in the `Authorization` header as a Bearer token:
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+Now you can query resources that require authentication. For example, fetch your user profile:
+
+```graphql
+query {
+  user {
+    id
+    email
+    createdAt
+    organizations(first: 5) {
+      edges {
+        node {
+          id
+          name
+        }
+      }
+    }
+  }
+}
 ```
+
+## Make a mutation
+
+Mutations follow the same pattern: send a `POST` request with the `Authorization` header. For example, create an organization:
+
+```graphql
+mutation {
+  organizationCreate(input: {
+    name: "My Company"
+    slug: "my-company"
+  }) {
+    organization {
+      id
+      name
+      slug
+    }
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "data": {
+    "organizationCreate": {
+      "organization": {
+        "id": "org_abc123",
+        "name": "My Company",
+        "slug": "my-company"
+      }
+    }
+  }
+}
+```
+
+Every mutation accepts an `input` argument and returns a payload object. The payload contains the created or updated resource on success, or errors in the top-level `errors` array on failure.
+
+## Error handling basics
+
+When something goes wrong, the API returns errors in the standard GraphQL `errors` array:
+
+```json
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "Invalid credentials",
+      "extensions": {
+        "code": "INVALID_CREDENTIALS"
+      }
+    }
+  ]
+}
+```
+
+Check the `extensions.code` field for a machine-readable error code you can use to handle specific failures programmatically. See the [Error Handling](./error-handling.md) guide for the full list of error codes.
+
+## Next steps
+
+Now that you can authenticate and make requests, explore these guides to go deeper:
+
+- [Authentication](./authentication.md) — email/password, OAuth, magic links, MFA, API keys, and session management
+- [Authorization and Scopes](./authorization-and-scopes.md) — understand what each role can access and how scopes control permissions
+- [Pagination](./pagination.md) — navigate large result sets with cursor-based pagination
+- [Error Handling](./error-handling.md) — handle every error code the API can return