steipete--codexbar/docs/factory.md

summary, read_when

summary	read_when
Factory (Droid) provider data sources: API key, browser cookies, WorkOS tokens, and Factory APIs.	Debugging Factory/Droid usage fetch Updating Factory cookie, API key, or WorkOS token handling Adjusting Factory provider UI/menu behavior

Factory (Droid) provider

Factory (displayed as "Droid") supports API-key and web-based auth. Source mode can be auto, api, or web.

Data sources + fallback order

API (api)

1. Resolve a Factory API key from, in order:
   • ~/.codexbar/config.json providers[].apiKey for factory (also via Settings or codexbar config set-api-key --provider factory)
   • FACTORY_API_KEY
   • optional ~/.factory/.env (FACTORY_API_KEY=… or export FACTORY_API_KEY=…)
2. Call Factory APIs with Authorization: Bearer <apiKey> (same billing-limits / bearer path as session tokens).

Web (web)

Fetch attempts run in this exact order:

1. Cached cookie header (Keychain cache com.steipete.codexbar.cache, account cookie.factory).
2. Stored session (~/Library/Application Support/CodexBar/factory-session.json).
3. Stored bearer token (same session file).
4. Stored WorkOS refresh token (same session file).
5. Local storage WorkOS tokens (Safari + Chrome/Chromium/Arc leveldb).
6. Browser cookies (Safari only) for Factory domains.
7. WorkOS cookies (Safari) to mint tokens.
8. Browser cookies (Chrome, Firefox) for Factory domains.
9. WorkOS cookies (Chrome, Firefox) to mint tokens.

If a step succeeds, we cache cookies/tokens back into the session store.

Manual option:

• Preferences → Providers → Droid → Cookie source → Manual.
• Paste the Cookie: header from app.factory.ai.

Auto (auto)

1. Try API first when a key is resolvable.
2. Fall back to web strategies on missing/unauthorized keys and other recoverable API failures (timeouts, DNS/network errors, 5xx, parse failures). Cancellation does not fall back.
3. Explicit api mode stays strict and does not fall back to web.
4. When both an API key and a browser/WorkOS session are available, Auto may surface the API-key account rather than the browser session. Use explicit web (or api) to pin account precedence.

Settings

• Preferences → Providers → Droid:
  • Usage source: Auto, API key, Browser cookies
  • API key: optional override for FACTORY_API_KEY / ~/.factory/.env
  • Cookie source: Automatic / Manual (web path)

CLI

printf '%s' "$FACTORY_API_KEY" | codexbar config set-api-key --provider factory --stdin
codexbar usage --provider factory --source api
codexbar usage --provider factory --source web

Cookie import

• Cookie domains: factory.ai, app.factory.ai, auth.factory.ai.
• Cookie names considered a session:
  • wos-session
  • __Secure-next-auth.session-token
  • next-auth.session-token
  • __Secure-authjs.session-token
  • __Host-authjs.csrf-token
  • authjs.session-token
  • session
  • access-token
• Stale-token retry filters:
  • access-token, __recent_auth.

Base URL selection

• Candidates are tried in order (deduped):
  • https://auth.factory.ai
  • https://api.factory.ai
  • https://app.factory.ai
  • baseURL (default https://app.factory.ai)
• Cookie domains influence candidate ordering (auth domain first if present).

Factory API endpoints

All requests set:

• Accept: application/json
• Content-Type: application/json
• Origin: https://app.factory.ai
• Referer: https://app.factory.ai/
• x-factory-client: web-app
• Authorization: Bearer <token> when a bearer token / API key is available.
• Cookie: <session cookies> when cookies are available.

Endpoints:

• GET https://api.factory.ai/api/billing/limits
  • Preferred when the account uses token-rate-limits billing (5h / weekly / monthly windows).
• GET <baseURL>/api/app/auth/me
  • Returns org + subscription metadata + feature flags.
• GET <baseURL>/api/organization/subscription/usage
  • Query: useCache=true and optional userId
  • Returns Standard + Premium token usage and billing window.

WorkOS token minting

• Endpoint:
  • POST https://api.workos.com/user_management/authenticate
• Body:
  • client_id: one of
    • client_01HXRMBQ9BJ3E7QSTQ9X2PHVB7
    • client_01HNM792M5G5G1A2THWPXKFMXB
  • grant_type: refresh_token
  • refresh_token: from local storage or session store
  • Optional: organization_id
  • When using cookies: useCookie: true + Cookie: <workos.com cookies>

Local storage WorkOS token extraction

• Safari:
  • Root: ~/Library/Containers/com.apple.Safari/Data/Library/WebKit/WebsiteData/Default
  • Finds origin files containing app.factory.ai or auth.factory.ai, then reads LocalStorage/localstorage.sqlite3.
• Chrome/Chromium/Arc/Helium:
  • Roots under ~/Library/Application Support/<Browser>/User Data/<Profile>/Local Storage/leveldb.
  • Helium uses ~/Library/Application Support/net.imput.helium/<Profile>/Local Storage/leveldb (no User Data).
  • Scans LevelDB files for workos:refresh-token and workos:access-token.
• Parsed tokens:
  • workos:refresh-token (required)
  • workos:access-token (optional)
  • Organization ID parsed from JWT when available.

Session storage

• File: ~/Library/Application Support/CodexBar/factory-session.json
• Stores cookies + bearer token + WorkOS refresh token.

Snapshot mapping

• Token-rate-limits accounts: primary 5h, secondary weekly, tertiary monthly (+ optional Core windows).
• Legacy Standard/Premium accounts: primary Standard, secondary Premium; reset at billing period end.
• Plan/tier + org name from auth response.

Troubleshooting

• Missing API key: set FACTORY_API_KEY, Settings → Droid → API key, or codexbar config set-api-key --provider factory.
• Unauthorized API key (401/403): regenerate at app.factory.ai/settings/api-keys.
• Missing session: log in to app.factory.ai in a supported browser, or paste a Cookie header in Manual mode.

Key files

• Sources/CodexBarCore/Providers/Factory/FactoryProviderDescriptor.swift
• Sources/CodexBarCore/Providers/Factory/FactorySettingsReader.swift
• Sources/CodexBarCore/Providers/Factory/FactoryStatusProbe.swift
• Sources/CodexBarCore/Providers/Factory/FactoryLocalStorageImporter.swift