@picked/client 0.0.61 → 0.0.62-next.10

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

package/dist/docs/api/pagination.md

@@ -0,0 +1,176 @@
+---
+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.
+
+## Connection pattern
+
+Paginated fields return a **connection** object with the following shape:
+
+```graphql
+type ExampleConnection {
+  edges: [ExampleEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type ExampleEdge {
+  cursor: String!
+  node: Example!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+| 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 |
+
+## 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.
+
+### First page
+
+Omit the `after` argument to fetch the first page:
+
+```graphql
+query {
+  organizations(input: { first: 10 }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+### Next page
+
+Pass the `endCursor` from the previous response as the `after` argument:
+
+```graphql
+query {
+  organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+## Checking for more pages
+
+Before requesting the next page, check the `hasNextPage` field:
+
+- `hasNextPage: true` — more results are available; pass `endCursor` to the next request's `after` argument
+- `hasNextPage: false` — all results have been fetched; stop paginating
+
+## Full paginated query example
+
+The following example fetches all members of an organization, page by page:
+
+```graphql
+# Page 1
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20) {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+If `pageInfo.hasNextPage` is `true`, fetch the next page:
+
+```graphql
+# Page 2
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20, after: "cursor_from_page_1") {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+Continue until `hasNextPage` returns `false`.
+
+## Paginated fields
+
+The following fields in the schema return connection types and support `first`/`after` pagination:
+
+| Parent Type | Field | Connection Type |
+|------------|-------|----------------|
+| `Query` | `organizations` | `OrganizationConnection` |
+| `User` | `organizations` | `OrganizationConnection` |
+| `User` | `invitations` | `ViewerInvitationConnection` |
+| `Organization` | `members` | `OrganizationMemberConnection` |
+| `Organization` | `invitations` | `OrganizationInvitationConnection` |
+| `Organization` | `projects` | `ProjectConnection` |
+| `Project` | `reports` | `ProjectReportConnection` |
+
+All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
+
+## 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.

package/dist/docs/image-optimisation-service.md

@@ -0,0 +1,72 @@
+---
+layout: docs
+---
+
+# Image optimisation service
+
+The Picked image optimisation service is a hosted endpoint at `https://img.picked-content.com`. It fetches images from allowed source domains, resizes them, re-encodes to modern formats (WebP or AVIF), and caches the result.
+
+## Endpoint
+
+```
+GET https://img.picked-content.com/_next/image?url={source}&w={width}&q={quality}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `url` | URL-encoded URL of the source image. Must point to an allowed source domain (see below). |
+| `w` | Target width in pixels. Must match one of the supported widths. |
+| `q` | Target quality (`25`, `50`, `75`, or `100`). |
+
+The service performs content negotiation: if the requesting browser advertises `image/avif` or `image/webp` in its `Accept` header, the response uses that format. Otherwise the response uses the source format.
+
+## Allowed source domains
+
+The service only fetches from these hostnames:
+
+- `**.picked.app`
+
+A request whose `url` parameter resolves to any other hostname returns `400 Bad Request`.
+
+## Supported widths
+
+```
+640, 750, 828, 1080, 1200, 1920, 2048, 3840
+```
+
+Requests with any other width return `400 Bad Request`. Pick the smallest width that covers your target rendering size at the user's device pixel ratio.
+
+## Supported qualities
+
+```
+25, 50, 75, 100
+```
+
+Lower values reduce bandwidth significantly. `75` is a good default for most images; use `25` or `50` for thumbnails on slow networks.
+
+## Responsive images
+
+Combine the endpoint with the standard `srcset` attribute to let browsers pick the right width per viewport:
+
+```html
+<img
+  src="https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75"
+  srcset="
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=640&q=75 640w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75 1080w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1920&q=75 1920w
+  "
+  sizes="(max-width: 768px) 100vw, 720px"
+  alt="..."
+/>
+```
+
+## Caching
+
+Optimised responses are cached by the upstream CDN. The minimum cache TTL is 60 seconds; the actual lifetime depends on the CDN's eviction policy. If you change the source image at the same URL, expect the optimised variant to remain cached for at least that interval.
+
+## Security
+
+- SVG sources are not optimised. Requests for SVG return the original bytes if the source is allowed; the service never executes embedded scripts.
+- Optimised responses carry a strict `Content-Security-Policy` (`default-src *; script-src 'none'; sandbox;`) so even a compromised source cannot run scripts in a viewing browser.
+- The response uses `Content-Disposition: inline`, never `attachment`.

package/dist/docs/index.md

@@ -26,7 +26,6 @@ Add the SDK to your site and initialize the client. Copy the snippet from your p
 import { createClient } from '@picked/client'
 
 const picked = createClient({
-  organizationId: 'your-organization-id',
   projectId: 'your-project-id',
   plugins: [],
 })
@@ -44,7 +43,6 @@ Register components when creating the client. Each key in the `components` objec
 import { createClient } from '@picked/client'
 
 const picked = createClient({
-  organizationId: 'your-organization-id',
   projectId: 'your-project-id',
   components: {
     'welcome-survey': YourComponent,

package/dist/docs/pickedql/data-sources.md

@@ -104,8 +104,8 @@ Columns returned:
 
 | Column | Type | Description |
 |---|---|---|
-| `source` | String | Edge start, formatted as `NN. step_id` (e.g., `01. welcome`). |
-| `target` | String | Edge end, formatted as `NN. step_id`. |
+| `source` | String | Edge start, formatted as `NN. <step title>` (e.g., `001. Welcome screen`). PickedQL joins `steps` to resolve the title. |
+| `target` | String | Edge end, formatted as `NN. <step title>`. |
 | `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
 
 :::note

package/dist/docs/pickedql/dimensions.md

@@ -26,6 +26,8 @@ The `steps`, `experiences`, and `projects` sources are reference tables sourced
 | `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
 | `projects` | `WHERE id = '<project_id>'` (the row's `id` IS the project id) |
 
+When auto-joined, these reference tables also receive a tenant equality on the JOIN's `ON` clause (e.g. `AND st.project_id = '<project_id>'`, `AND pr.id = '<project_id>'`) so ClickHouse prunes the dim scan instead of reading the full table. The predicate is added to `ON` rather than `WHERE` to preserve `LEFT JOIN` semantics.
+
 Analyst-facing column names are prefixed (`step_title`, `project_name`, etc.) to avoid collisions across sources — for example, `steps.title` and `experiences.title` both exist, but you reference them as `step_title` and `experience_title`.
 
 ```sql