:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { ApiClient, GroupType } from '@/api/client'
import type { Schemas } from '@/api/generated'
import { hasScope } from '@/lib/api'
import { classifyAuthFailure } from '@/lib/auth-errors'
import { classifyAuthMethod } from '@/lib/auth-method'
import type { ScopedCache } from '@/lib/cache/ScopedCache'
import { StateLookupCache } from '@/lib/cache/StateLookupCache'
import {
ErrorCode,
hasTimeoutCause,
MissingOrganizationContextError,
MissingProjectContextError,
PostHogApiError,
wrapError,
} from '@/lib/errors'
import { getPostHogClient } from '@/lib/posthog'
import { sanitizeHeaderValue } from '@/lib/utils'
import type { ApiUser } from '@/schema/api'
import type {
BusinessKnowledgeContent,
CachedOrg,
CachedProject,
CachedUser,
PinnedActiveContext,
SessionScopedState,
State,
} from '@/tools/types'
const CACHE_TTL_MS = 10 * 60 * 1000 // 10 minutes
// A personal API key keeps its value when its scopes change, and the cache is keyed by token, so
// its scopes are read again after this delay. Reconnecting the client does not help: same token.
export const API_KEY_CACHE_TTL_MS = 2 * 60 * 1000 // 2 minutes
const GATEWAY_TOOLS_CACHE_TTL_MS = 2 * 60 * 1000 // 2 minutes
// An empty answer is re-read sooner so that newly added data shows up within a minute.
const NO_DATA_CACHE_TTL_MS = 60 * 1000 // 1 minute
// The integration list only adds a line to the environment prompt, so a slow response must not
// hold `switch-project` for the full default request deadline. The caller serves the cached list.
const INTEGRATION_KINDS_TIMEOUT_MS = 10 * 1000
const BUSINESS_KNOWLEDGE_CONTENT_TIMEOUT_MS = 3 * 1000
// Entitlement-related fields shared by both org shapes we read from — the
// standalone org endpoint and the org embedded in `/api/users/@me/`.
type OrgEntitlementFields = {
is_ai_data_processing_approved?: boolean | null
available_product_features?: Array<{ key: string }> | null
}
export class StateManager {
private _pinnedOrgProject: Promise<string> | undefined
constructor(
private readonly _cache: ScopedCache<State>,
private readonly _api: ApiClient,
private readonly _pinned?: PinnedActiveContext,
private readonly _sessionCache?: ScopedCache<SessionScopedState>,
private readonly lookups = new StateLookupCache()
) {}
get pinnedContext(): PinnedActiveContext | undefined {
return this._pinned
}
/**
* Session selections never enter the token cache because other sessions on
* the credential share it. Sessionless pins persist only the keys they leave open.
*/
async setActiveContext(updates: { orgId?: string; projectId?: string }): Promise<void> {
const pinned = this._pinned
if (!pinned) {
await this._cache.setMany({
...(updates.orgId ? { orgId: updates.orgId } : {}),
...(updates.projectId ? { projectId: updates.projectId } : {}),
})
return
}
if (updates.orgId) {
if (updates.orgId !== pinned.orgId && !updates.projectId) {
pinned.projectId = undefined
}
pinned.orgId = updates.orgId
}
if (updates.projectId) {
pinned.projectId = updates.projectId
}
this._pinnedOrgProject = undefined
if (pinned.sessionScoped) {
await this._sessionCache?.setMany({
activeOrgId: pinned.orgId ?? null,
activeProjectId: pinned.projectId ?? null,
})
} else {
await this._cache.setMany({
...(updates.orgId && !pinned.pin.organizationId && !pinned.pin.projectId
? { orgId: updates.orgId }
: {}),
...(updates.projectId && !pinned.pin.projectId ? { projectId: updates.projectId } : {}),
})
}
}
private async _fetchUser(): Promise<ApiUser> {
const userResult = await this._api.users().me()
if (!userResult.success) {
throw wrapError(`Failed to get user: ${userResult.error.message}`, userResult.error)
}
return userResult.data
}
async getUser(): Promise<ApiUser> {
return this.lookups.get(this._cache.scope, 'user', () => this._fetchUser())
}
private async _fetchApiKey(): Promise<NonNullable<State['apiKey']>> {
const apiKeyResult = await this._api.apiKeys().current()
if (apiKeyResult.success) {
const { scopes, scoped_teams, scoped_organizations } = apiKeyResult.data
// The DRF serializer returns `null` (not `[]`) for unscoped keys, so
// normalize at the boundary — downstream code treats these as arrays.
return {
scopes: scopes ?? [],
scoped_teams: scoped_teams ?? [],
scoped_organizations: scoped_organizations ?? [],
is_impersonated: false,
suppress_analytics: false,
}
}
const introspectionResult = await this._api.oauth().introspect({ token: this._api.config.apiToken })
if (!introspectionResult.success) {
// Only a 401 or 403 rejects the token. Self-introspection returns 403 when the token
// no longer exists, for example after a refresh rotated it. Any other failure means
// the check did not run, and a rejection would make the client discard a valid token.
const { error } = introspectionResult
if (
error.message.includes(ErrorCode.INVALID_API_KEY) ||
(error instanceof PostHogApiError && error.status === 403)
) {
throw new Error(ErrorCode.INVALID_API_KEY)
}
throw wrapError('Failed to introspect OAuth token', error)
}
if (!introspectionResult.data.active) {
throw new Error(ErrorCode.INACTIVE_OAUTH_TOKEN)
}
const { scope, scoped_teams, scoped_organizations, client_name, client_id } = introspectionResult.data
// Which OAuth application minted this token. Introspection is server-derived, so unlike
// the consumer header the caller cannot set it, which is what makes it usable as the
// first-party gate in `resolveEventSource`. Django gates on the same id set.
if (client_id) {
await this._cache.set('oauthClientId', client_id)
}
const sanitizedClientName = sanitizeHeaderValue(client_name)
if (sanitizedClientName) {
await this._cache.set('clientName', sanitizedClientName)
}
return {
scopes: scope ? scope.split(' ') : [],
scoped_teams: scoped_teams ?? [],
scoped_organizations: scoped_organizations ?? [],
is_impersonated: introspectionResult.data.is_impersonated === true,
// Only server-minted sandbox tokens can carry this scope; request headers cannot opt out.
suppress_analytics: (scope ?? '').split(' ').includes('scout_experiment_internal:read'),
...(introspectionResult.data.sandbox_task_id
? { sandbox_task_id: introspectionResult.data.sandbox_task_id }
: {}),
...(introspectionResult.data.mcp_allowed_tools
? { mcp_allowed_tools: introspectionResult.data.mcp_allowed_tools }
: {}),
...(introspectionResult.data.supports_step_up === true ? { supports_step_up: true } : {}),
}
}
private async _getApiKey(): Promise<NonNullable<State['apiKey']>> {
// An OAuth token gets a new value, and so a new cache entry, whenever its scopes change.
const refreshable = classifyAuthMethod(this._api.config.apiToken) !== 'oauth'
const [cached, fetchedAt] = await Promise.all([
this._cache.get('apiKey'),
refreshable ? this._cache.get('apiKeyFetchedAt') : undefined,
])
if (cached && (!refreshable || !this.isCacheStale(fetchedAt, API_KEY_CACHE_TTL_MS))) {
return cached
}
try {
const apiKey = await this.lookups.get(this._cache.scope, JSON.stringify(['apiKey', fetchedAt]), () =>
this._fetchApiKey()
)
await Promise.all([
this._cache.set('apiKey', apiKey),
refreshable ? this._cache.set('apiKeyFetchedAt', Date.now()) : undefined,
])
return apiKey
} catch (error) {
if (!cached) {
throw error
}
// A failed refresh must not end a live session. Every API call is authorized again
// server-side, so the last known scopes cannot grant access the key does not hold.
// A rejected credential is an expected outcome, not a fault, so only report other failures.
const { reason } = classifyAuthFailure(error)
if (reason !== 'invalid_api_key' && reason !== 'inactive_oauth_token') {
this._reportException(error, 'api_key_refresh_failed')
}
await this._cache.set('apiKeyFetchedAt', Date.now()).catch(() => {})
return cached
}
}
async getApiKey(): Promise<NonNullable<State['apiKey']>> {
const apiKey = await this._getApiKey()
const clientName = await this._cache.get('clientName')
if (clientName) {
this._api.config.oauthClientName = sanitizeHeaderValue(clientName)
}
return apiKey
}
async getDistinctId(): Promise<NonNullable<State['distinctId']>> {
let _distinctId = await this._cache.get('distinctId')
if (!_distinctId) {
const user = await this.getUser()
await this._cache.set('distinctId', user.distinct_id)
_distinctId = user.distinct_id
}
return _distinctId
}
private async _getDefaultOrganizationAndProject(): Promise<NonNullable<SessionScopedState['defaultContext']>> {
const sessionCache = this._pinned?.sessionScoped ? this._sessionCache : undefined
if (!sessionCache) {
return this._fetchDefaultOrganizationAndProject()
}
const saved = await sessionCache.get('defaultContext')
if (saved) {
if (saved.projectId !== undefined || !saved.organizationId) {
return saved
}
const cachedProjectId = await sessionCache.get('defaultProjectId')
if (cachedProjectId !== undefined) {
return { ...saved, projectId: cachedProjectId }
}
const projectId = await this._fetchDefaultProjectInOrganization(saved.organizationId)
if (projectId !== undefined) {
await sessionCache.setIfAbsent('defaultProjectId', projectId)
}
return { ...saved, projectId: await sessionCache.get('defaultProjectId') }
}
const defaults = await this._fetchDefaultOrganizationAndProject()
if (!defaults.organizationId && defaults.projectId === undefined) {
return defaults
}
if (await sessionCache.setIfAbsent('defaultContext', defaults)) {
return defaults
}
return (await sessionCache.get('defaultContext')) ?? defaults
}
private async _fetchDefaultOrganizationAndProject(): Promise<NonNullable<SessionScopedState['defaultContext']>> {
const [{ scoped_organizations, scoped_teams }, user] = await Promise.all([this.getApiKey(), this.getUser()])
const { organization: activeOrganization, team: activeTeam } = user
// Team-scoped key: prefer the active team if the scope allows it,
// otherwise pick the first scoped team deterministically. The org is
// omitted here — `getAnalyticsContext` recovers it from the project.
if (scoped_teams.length > 0) {
if (activeTeam && scoped_teams.includes(activeTeam.id)) {
return { projectId: activeTeam.id }
}
return { projectId: scoped_teams[0]! }
}
// No team scoping: prefer the user's active org/team when the scope
// allows it. `activeOrganization` / `activeTeam` can be null for users
// with no `current_organization` / `current_team` (newly provisioned
// accounts, users who left their last org) — fall through to the
// scoped-org fallback below when either is missing.
if (
activeOrganization &&
(scoped_organizations.length === 0 || scoped_organizations.includes(activeOrganization.id))
) {
return activeTeam
? { organizationId: activeOrganization.id, projectId: activeTeam.id }
: { organizationId: activeOrganization.id }
}
// Active org isn't in the scope (or the user has no active org). Pick
// the first allowed org and fall back to its first project. If the
// project lookup fails or the org has no projects, return the org alone
// and let the agent disambiguate. With no scoped orgs and no active
// org, we have nothing to anchor on — return empty and let the caller
// surface a recoverable missing-context error.
const organizationId = scoped_organizations[0]
if (!organizationId) {
return {}
}
return { organizationId, projectId: await this._fetchDefaultProjectInOrganization(organizationId) }
}
private async _fetchDefaultProjectInOrganization(organizationId: string): Promise<number | undefined> {
try {
const projects = await this.lookups.get<Schemas.ProjectBackwardCompat[]>(
this._cache.scope,
`organizationProjects:${organizationId}`,
async () => {
const result = await this._api.organizations().projects({ orgId: organizationId }).list()
if (!result.success) {
throw result.error
}
return result.data
}
)
return projects.length > 0 ? Number(projects[0]!.id) : undefined
} catch (error) {
if (this._isRecoverableNotFound(error)) {
console.warn(
`[StateManager] Scoped org ${organizationId} projects lookup returned 404 (org not accessible to this user or deleted); falling back to org-only context`
)
} else {
await this._reportException(error, 'default_org_project_projects_list_failed', {
organization_id: organizationId,
})
}
}
return undefined
}
/**
* A 404 from the scoped-org projects lookup is an expected missing-context
* state (org deleted, or the user lost access to a still-scoped org), not a
* service bug. Treat it as recoverable so it stays out of error tracking.
*/
private _isRecoverableNotFound(error: unknown): boolean {
return error instanceof PostHogApiError && error.status === 404
}
private async _reportException(
error: unknown,
context: string,
extra: Record<string, unknown> = {}
): Promise<void> {
try {
// This also reports key-refresh failures, so resolving the key again can recurse.
const apiKey = await this._cache.get('apiKey').catch(() => undefined)
getPostHogClient().captureException(error, undefined, {
tag: 'mcp',
team: 'posthog_ai',
context,
...extra,
suppress_analytics: apiKey?.suppress_analytics === true,
})
} catch {
// Never let observability break the request.
}
}
async setDefaultOrganizationAndProject(): Promise<{
organizationId: string | undefined
projectId: number | undefined
}> {
const { organizationId, projectId } = await this._getDefaultOrganizationAndProject()
if (this._pinned?.sessionScoped) {
this._pinned.orgId = organizationId
this._pinned.projectId = projectId?.toString()
} else {
await this.setActiveContext({ orgId: organizationId, projectId: projectId?.toString() })
}
return { organizationId, projectId }
}
/**
* Resolve an organization id without throwing. Reads the cache, then falls
* back to the API key's default-org resolution, then derives the org from
* the cached project (matches the team-scoped key path in
* `_getDefaultOrganizationAndProject` which intentionally omits the org).
*
* The derived org id is written back to the cache so subsequent calls
* short-circuit on the first read — without this, every team-scoped tool
* invocation would re-hit `setDefaultOrganizationAndProject` plus a project
* fetch.
*/
private async _resolveOrganizationId(): Promise<string | undefined> {
const pinned = this._pinned
if (pinned?.orgId) {
return pinned.orgId
}
// A pinned project owns the org. The shared token cache can hold another
// session's org, so when the project cannot name its org, report missing
// context instead of falling back to the cache.
if (pinned?.projectId) {
const project = await this.getCachedOrFetchProject().catch(() => undefined)
pinned.orgId = project?.organization ?? undefined
return pinned.orgId
}
if (pinned) {
return undefined
}
const cached = await this._cache.get('orgId')
if (cached) {
return cached
}
const { organizationId } = await this.setDefaultOrganizationAndProject()
if (organizationId) {
return organizationId
}
const project = await this.getCachedOrFetchProject().catch(() => undefined)
const derived = project?.organization
if (derived) {
await this._cache.set('orgId', derived)
}
return derived
}
async getOrgID(): Promise<string> {
const orgId = await this._resolveOrganizationId()
if (!orgId) {
throw new MissingOrganizationContextError()
}
return orgId
}
async getProjectId(): Promise<string> {
const pinned = this._pinned
if (pinned) {
if (pinned.projectId) {
return pinned.projectId
}
this._pinnedOrgProject ??= this._resolvePinnedOrgProjectId(pinned)
return this._pinnedOrgProject
}
const projectId = await this._cache.get('projectId')
if (!projectId) {
const { organizationId, projectId: resolved } = await this.setDefaultOrganizationAndProject()
if (resolved === undefined) {
throw new MissingProjectContextError({ organizationId })
}
return resolved.toString()
}
return projectId
}
/**
* An organization selection can outlive its project, so accept a default only
* when its lookup proves that it belongs to the selected org. Sessionless
* requests also consider the token selection for compatibility.
*/
private async _resolvePinnedOrgProjectId(pinned: PinnedActiveContext): Promise<string> {
const orgId = pinned.orgId
const belongsToOrg = async (candidate: string | undefined): Promise<boolean> => {
if (!orgId || !candidate) {
return false
}
const project = await this._getCachedOrFetchProjectById(candidate).catch(() => undefined)
return project?.organization === orgId
}
const cachedCandidate = pinned.sessionScoped ? undefined : await this._cache.get('projectId')
if (await belongsToOrg(cachedCandidate)) {
return cachedCandidate!
}
const { organizationId, projectId } = await this._getDefaultOrganizationAndProject().catch(() => ({
organizationId: undefined,
projectId: undefined,
}))
const defaultCandidate = projectId?.toString()
if (
defaultCandidate &&
defaultCandidate !== cachedCandidate &&
((organizationId !== undefined && organizationId === orgId) || (await belongsToOrg(defaultCandidate)))
) {
if (pinned.sessionScoped) {
pinned.projectId = defaultCandidate
}
return defaultCandidate
}
throw new MissingProjectContextError({ organizationId: orgId })
}
private isCacheStale(fetchedAt: number | undefined, ttlMs: number = CACHE_TTL_MS): boolean {
return !fetchedAt || Date.now() - fetchedAt > ttlMs
}
/**
* Stale-while-cached helper. Returns fresh cached data if available; otherwise
* fetches, writes both the value and its timestamp, and returns the fresh value.
* On fetcher failure, returns the last-known cached value (possibly `undefined`)
* and captures the exception.
*/
private async getOrFetchCached<D extends keyof State, F extends keyof State>(opts: {
name: string
cacheKey: D
fetchedAtKey: F
fetcher: () => Promise<NonNullable<State[D]>>
ttlMs?: number | ((cached: State[D]) => number)
/** Skip the error report when the fetch hits its deadline. Use it for optional data with a short timeout. */
expectTimeouts?: boolean
}): Promise<State[D]> {
const [cached, fetchedAt] = (await Promise.all([
this._cache.get(opts.cacheKey),
this._cache.get(opts.fetchedAtKey),
])) as [State[D], number | undefined]
const ttlMs = typeof opts.ttlMs === 'function' ? opts.ttlMs(cached) : opts.ttlMs
if (!this.isCacheStale(fetchedAt, ttlMs)) {
return cached
}
try {
const data = await this.lookups.get(
this._cache.scope,
JSON.stringify([opts.cacheKey, fetchedAt]),
opts.fetcher
)
await Promise.all([
this._cache.set(opts.cacheKey, data as State[D]),
this._cache.set(opts.fetchedAtKey, Date.now() as State[F]),
])
return data as State[D]
} catch (error) {
if (!(opts.expectTimeouts && hasTimeoutCause(error))) {
this._reportException(error, `get_or_fetch_${opts.name}`)
}
await this._cache.set(opts.fetchedAtKey, Date.now() as State[F]).catch(() => {})
return cached
}
}
async getCachedOrFetchUser(): Promise<CachedUser | undefined> {
const distinctId = await this.getDistinctId()
return this.getOrFetchCached({
name: 'user',
cacheKey: `cachedUser:${distinctId}` as const,
fetchedAtKey: `cachedUserFetchedAt:${distinctId}` as const,
fetcher: () => this.getUser(),
})
}
async getCachedOrFetchOrg(): Promise<CachedOrg | undefined> {
const apiKey = await this.getApiKey()
// `/api/organizations/{id}/` is not project-nested. Backend permission
// checks reject project-scoped tokens there even when they carry
// `organization:read` or `*`, so skip the best-effort fetch entirely.
if (apiKey.scoped_teams.length > 0 || !hasScope(apiKey.scopes, 'organization:read')) {
return undefined
}
// Non-throwing: consent checks treat "no org" as "skip", not as an error.
const orgId = await this._resolveOrganizationId()
if (!orgId) {
return undefined
}
return this.getOrFetchCached({
name: 'org',
cacheKey: `cachedOrg:${orgId}` as const,
fetchedAtKey: `cachedOrgFetchedAt:${orgId}` as const,
fetcher: async () => {
const result = await this._api.organizations().get({ orgId })
if (!result.success) {
throw result.error
}
return result.data
},
})
}
async getCachedOrFetchProject(): Promise<CachedProject | undefined> {
const projectId = await this.getProjectId()
if (!projectId) {
return undefined
}
return this._getCachedOrFetchProjectById(projectId)
}
private async _getCachedOrFetchProjectById(projectId: string): Promise<CachedProject | undefined> {
return this.getOrFetchCached({
name: 'project',
cacheKey: `cachedProject:${projectId}` as const,
fetchedAtKey: `cachedProjectFetchedAt:${projectId}` as const,
fetcher: async () => {
const result = await this._api.projects().get({ projectId })
if (!result.success) {
throw result.error
}
return result.data
},
})
}
async getOrFetchGroupTypes(projectId: string): Promise<GroupType[] | undefined> {
return this.getOrFetchCached({
name: 'group_types',
cacheKey: `groupTypes:${projectId}` as const,
fetchedAtKey: `groupTypesFetchedAt:${projectId}` as const,
fetcher: () => this._api.getGroupTypes(projectId),
})
}
/**
* Integration kinds (github, slack, ...) connected in the project, for the
* environment prompt. Returns undefined when the key lacks `integration:read`
* so the prompt renders nothing rather than a false "none connected".
*/
async getOrFetchIntegrationKinds(projectId: string): Promise<string[] | undefined> {
const apiKey = await this.getApiKey()
if (!hasScope(apiKey.scopes, 'integration:read')) {
return undefined
}
return this.getOrFetchCached({
name: 'integration_kinds',
cacheKey: `integrationKinds:${projectId}` as const,
fetchedAtKey: `integrationKindsFetchedAt:${projectId}` as const,
fetcher: async () => {
const result = await this._api.request<Schemas.PaginatedIntegrationConfigList>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(projectId)}/integrations/`,
query: { limit: 100 },
timeoutMs: INTEGRATION_KINDS_TIMEOUT_MS,
})
return [...new Set((result.results ?? []).map((integration) => String(integration.kind)))].sort()
},
expectTimeouts: true,
})
}
/** An empty project is re-read on the short TTL, so a source the user just added gets its search guidance within a minute. */
async getOrFetchBusinessKnowledgeContent(projectId: string): Promise<BusinessKnowledgeContent | undefined> {
return this.getOrFetchCached({
name: 'business_knowledge_content',
cacheKey: `businessKnowledgeContent:${projectId}` as const,
fetchedAtKey: `businessKnowledgeContentFetchedAt:${projectId}` as const,
fetcher: async () => {
const availability = await this._api.request<{ has_sources?: unknown; has_repositories?: unknown }>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(projectId)}/business_knowledge/sources/availability/`,
timeoutMs: BUSINESS_KNOWLEDGE_CONTENT_TIMEOUT_MS,
signal: AbortSignal.timeout(BUSINESS_KNOWLEDGE_CONTENT_TIMEOUT_MS),
})
return {
hasSources: typeof availability.has_sources === 'boolean' ? availability.has_sources : undefined,
hasRepositories:
typeof availability.has_repositories === 'boolean' ? availability.has_repositories : undefined,
}
},
ttlMs: (cached) =>
cached?.hasSources === false && cached.hasRepositories === false ? NO_DATA_CACHE_TTL_MS : CACHE_TTL_MS,
expectTimeouts: true,
})
}
/**
* The third-party MCP tools this user can reach, from the gateway.
*
* Shorter TTL than the other cached entities: connecting a server is a deliberate
* act and the user expects its tools to appear on the next command, not ten minutes
* later. Cheap enough to re-fetch — it's one request, and only `exec` triggers it.
*/
async getOrFetchGatewayTools(projectId: string): Promise<Schemas.AvailableToolsResponse | undefined> {
return this.getOrFetchCached({
name: 'gateway_tools',
cacheKey: `gatewayTools:${projectId}` as const,
fetchedAtKey: `gatewayToolsFetchedAt:${projectId}` as const,
fetcher: () => this._api.getGatewayTools(projectId),
ttlMs: GATEWAY_TOOLS_CACHE_TTL_MS,
})
}
/**
* Resolve the workspace identifiers used to attach analytics events to the
* `organization` and `project` PostHog groups. Reuses the cached user/org/project
* entities, so repeat calls within a session are cheap.
*/
async getAnalyticsContext(): Promise<{
organizationId?: string
projectId?: string
projectUuid?: string
projectName?: string
}> {
const [orgId, project] = await Promise.all([
this._pinned ? this._pinned.orgId : this._cache.get('orgId'),
this.getCachedOrFetchProject().catch(() => undefined),
])
return {
...(orgId
? { organizationId: orgId }
: project?.organization
? { organizationId: project.organization }
: {}),
...(project?.id !== undefined ? { projectId: String(project.id) } : {}),
...(project?.uuid ? { projectUuid: project.uuid } : {}),
...(project?.name ? { projectName: project.name } : {}),
}
}
/**
* Resolve a field from the active organization, failing closed to `undefined`.
*
* Tries `/api/organizations/{id}/` first. Team-scoped tokens (e.g. sandbox
* OAuth tokens) can never fetch that endpoint — see the guard in
* getCachedOrFetchOrg — so fall back to the org embedded in
* `/api/users/@me/` (exempt from team scoping). That embedded org is the
* user's *current* org, which isn't necessarily the one owning the scoped
* project, so only trust it when it matches the active project's owning org.
* Any failure resolves to `undefined` so callers keep failing closed.
*/
private async getOrgField<T>(extract: (org: OrgEntitlementFields) => T): Promise<T | undefined> {
try {
const org = await this.getCachedOrFetchOrg()
if (org) {
return extract(org as OrgEntitlementFields)
}
const [user, project] = await Promise.all([this.getCachedOrFetchUser(), this.getCachedOrFetchProject()])
if (user?.organization && project?.organization === user.organization.id) {
return extract(user.organization)
}
return undefined
} catch {
return undefined
}
}
async getAiConsentGiven(): Promise<boolean | undefined> {
const project = await this.getCachedOrFetchProject().catch(() => undefined)
if (project?.is_ai_data_processing_approved !== undefined) {
return !!project.is_ai_data_processing_approved
}
return this.getOrgField((org) => !!org.is_ai_data_processing_approved)
}
async getAvailableFeatures(): Promise<string[] | undefined> {
// A fetched org resolves to its entitlement keys, treating both `null`
// and a missing field as "no features" (`[]`) rather than falling
// through — the fallback only exists for tokens that can't fetch the org
// at all, where getCachedOrFetchOrg returns undefined.
return this.getOrgField((org) => {
const features = org.available_product_features
if (!Array.isArray(features)) {
return []
}
return features.map((f) => f.key).filter((k): k is string => typeof k === 'string')
})
}
}