@picked/client 0.0.61 → 0.0.62-next.10

package/dist/docs/api/authentication.md

@@ -0,0 +1,376 @@
+---
+layout: docs
+---
+
+# Authentication
+
+The Picked API supports multiple authentication methods: email/password sessions, OAuth providers, magic links, and API keys. This guide covers each method and explains how to manage sessions and multi-factor authentication (MFA).
+
+## Email and password login
+
+The `sessionCreate` mutation authenticates a user with email and password and returns a session.
+
+```graphql
+mutation {
+  sessionCreate(input: {
+    email: "user@example.com"
+    password: "secure-password"
+  }) {
+    session {
+      accessToken
+      refreshToken
+      expiresAt
+      user {
+        id
+        email
+      }
+      aal
+    }
+    requiresMfa
+    mfaFactors {
+      id
+      factorType
+      status
+    }
+  }
+}
+```
+
+If the user has MFA enabled, the response sets `requiresMfa` to `true` and returns the enrolled `mfaFactors`. The caller must complete an MFA challenge before receiving a fully authenticated session. See the [MFA](#multi-factor-authentication-mfa) section below.
+
+If MFA is not enabled, the response includes a `session` with an `accessToken`, a `refreshToken`, and an `expiresAt` timestamp.
+
+## Account creation
+
+New accounts are created with the `accountCreate` mutation:
+
+```graphql
+mutation {
+  accountCreate(input: {
+    email: "newuser@example.com"
+    password: "secure-password"
+    metadata: { firstName: "Jane", lastName: "Doe" }
+  }) {
+    user {
+      id
+      email
+    }
+    session {
+      accessToken
+      refreshToken
+    }
+  }
+}
+```
+
+The `metadata` field is optional and accepts arbitrary JSON for storing profile information. When email verification is required, the returned session is `null` until the email is verified.
+
+## Email verification
+
+After account creation, the user receives a verification email containing a token. The `accountVerifyEmail` mutation completes verification:
+
+```graphql
+mutation {
+  accountVerifyEmail(input: {
+    email: "newuser@example.com"
+    token: "verification-token-from-email"
+  }) {
+    session {
+      accessToken
+      refreshToken
+    }
+  }
+}
+```
+
+If the verification email needs to be resent:
+
+```graphql
+mutation {
+  accountResendVerification(input: {
+    email: "newuser@example.com"
+  }) {
+    success
+  }
+}
+```
+
+## OAuth flow (Google)
+
+The API supports Google as an OAuth provider. The flow has two steps.
+
+### Step 1: Get the authorization URL
+
+```graphql
+mutation {
+  oauthAuthorize(input: {
+    provider: GOOGLE
+    redirectUrl: "https://app.example.com/auth/callback"
+    scopes: ["openid", "email", "profile"]
+  }) {
+    url
+  }
+}
+```
+
+The caller redirects the user to the returned `url`. After the user authenticates with Google, they are redirected back to a URL on the same dashboard deployment with a `code` parameter, where the caller exchanges it for a session.
+
+### Step 2: Exchange the code for a session
+
+```graphql
+mutation {
+  oauthCallback(input: {
+    provider: GOOGLE
+    code: "auth-code-from-google"
+  }) {
+    session {
+      accessToken
+      refreshToken
+      expiresAt
+    }
+  }
+}
+```
+
+## Magic links
+
+Magic links allow passwordless authentication via email.
+
+### Send a magic link
+
+```graphql
+mutation {
+  magicLinkSend(input: {
+    email: "user@example.com"
+    redirectUrl: "https://app.example.com/auth/verify"
+  }) {
+    success
+  }
+}
+```
+
+The user receives an email containing a link with a token.
+
+### Verify the magic link
+
+```graphql
+mutation {
+  magicLinkVerify(input: {
+    email: "user@example.com"
+    token: "token-from-magic-link"
+  }) {
+    session {
+      accessToken
+      refreshToken
+    }
+  }
+}
+```
+
+## Password management
+
+### Reset a forgotten password
+
+Send a password reset email:
+
+```graphql
+mutation {
+  passwordResetSend(input: {
+    email: "user@example.com"
+    redirectUrl: "https://app.example.com/reset-password"
+  }) {
+    success
+  }
+}
+```
+
+Complete the reset with the token from the email:
+
+```graphql
+mutation {
+  passwordReset(input: {
+    email: "user@example.com"
+    token: "reset-token-from-email"
+    newPassword: "new-secure-password"
+  }) {
+    session {
+      accessToken
+      refreshToken
+    }
+  }
+}
+```
+
+### Update an existing password
+
+This mutation requires authentication:
+
+```graphql
+mutation {
+  passwordUpdate(input: {
+    currentPassword: "old-password"
+    newPassword: "new-secure-password"
+  }) {
+    success
+  }
+}
+```
+
+## Multi-factor authentication (MFA)
+
+MFA adds a second layer of security using phone-based verification. The API supports enrolling, challenging, verifying, and unenrolling MFA factors. All MFA mutations require authentication.
+
+### Enroll a factor
+
+```graphql
+mutation {
+  mfaFactorEnroll(input: {
+    factorType: PHONE
+    phone: "+15551234567"
+    friendlyName: "My Phone"
+  }) {
+    factor {
+      id
+      factorType
+      status
+    }
+  }
+}
+```
+
+A newly enrolled factor has a status of `UNVERIFIED` until confirmed via a challenge.
+
+### Send a challenge
+
+```graphql
+mutation {
+  mfaChallengeSend(input: {
+    factorId: "factor-id"
+  }) {
+    challengeId
+  }
+}
+```
+
+This sends a verification code to the enrolled phone number.
+
+### Verify the challenge
+
+```graphql
+mutation {
+  mfaChallengeVerify(input: {
+    factorId: "factor-id"
+    challengeId: "challenge-id"
+    code: "123456"
+  }) {
+    session {
+      accessToken
+      refreshToken
+      aal
+    }
+  }
+}
+```
+
+On success, the session is upgraded to Authenticator Assurance Level `AAL2`. The factor status changes to `VERIFIED`.
+
+### Unenroll a factor
+
+```graphql
+mutation {
+  mfaFactorUnenroll(input: {
+    factorId: "factor-id"
+  }) {
+    success
+  }
+}
+```
+
+## Using a session
+
+After obtaining a session, the caller includes the access token in the `Authorization` header of every authenticated request:
+
+```
+Authorization: Bearer <accessToken>
+```
+
+The `expiresAt` field on the session indicates when the access token expires. The caller should refresh the session before the token expires.
+
+### Authenticator assurance levels
+
+The session includes an `aal` field indicating the authentication strength:
+
+| Level | Meaning |
+|-------|---------|
+| `AAL1` | Single-factor authentication (email/password, OAuth, or magic link) |
+| `AAL2` | Multi-factor authentication (MFA challenge completed) |
+
+Some operations may require `AAL2`. If a caller with `AAL1` attempts such an operation, the API returns an authorization error.
+
+## Session refresh
+
+Access tokens are short-lived. The `sessionRefresh` mutation exchanges a refresh token for a new session:
+
+```graphql
+mutation {
+  sessionRefresh(input: {
+    refreshToken: "v1.refresh-token..."
+  }) {
+    session {
+      accessToken
+      refreshToken
+      expiresAt
+    }
+  }
+}
+```
+
+The response includes a new `accessToken` and a new `refreshToken`. The previous refresh token is invalidated. This mutation does not require the `Authorization` header.
+
+## API key authentication
+
+API keys provide long-lived, scoped access to the API. They are typically used for server-to-server integrations and automated workflows.
+
+To authenticate with an API key, include it in the `x-api-key` header:
+
+```
+x-api-key: pk_live_abc123...
+```
+
+API keys are scoped to an organization and optionally to a specific project. They carry a defined set of [authorization scopes](./authorization-and-scopes.md) that determine which operations the key can perform.
+
+See [API Keys](/api-keys) for managing keys from the dashboard UI.
+
+### Creating an API key
+
+The `apiKeyCreate` mutation creates a new API key. This mutation is only available to session-authenticated users (not other API keys):
+
+```graphql
+mutation {
+  apiKeyCreate(input: {
+    organizationId: "org-id"
+    name: "CI/CD Pipeline Key"
+    projectId: "project-id"
+    scopes: [ORGANIZATION_READ, ORGANIZATION_PROJECTS_READ]
+  }) {
+    apiKey
+  }
+}
+```
+
+The full API key string is returned only once in the response. Store it securely; it cannot be retrieved again.
+
+The requested scopes must be a subset of the creating user's scopes. See [Authorization and Scopes](./authorization-and-scopes.md) for more details.
+
+### Revoking an API key
+
+```graphql
+mutation {
+  apiKeyRevoke(input: {
+    keyId: "key-id"
+    organizationId: "org-id"
+  })
+}
+```
+
+Revoked keys are immediately invalidated and cannot be used for further requests.

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`.