Tokens & Features

When bucket="auto", the app first decides whether the request is happening in a personal workspace or an organization workspace.

1. In an organization workspace, auto always targets the shared workspace bucket.
2. In a personal workspace, auto tries paid first and then free.
3. Auto never crosses those boundaries: organization context does not spill into personal buckets, and personal context does not reach into shared workspace balance.

The active workspace context is resolved at spend time from the current authenticated request and active-organization state. Switching workspaces later does not retroactively move an already-recorded spend into a different bucket.

The workspace maintains one shared balance in Organization.tokenBalance. All members draw from the same pool.

In SOFT mode the app can warn while still allowing overage. In HARD mode the spend can be blocked once the member exceeds the current cap window.

Each active member gets their own workspace balance on the membership record instead of drawing from one shared pool.

Renewals can reset these balances, and one-time top-ups can credit each active member rather than a shared pool.

Those resets follow the workspace subscription lifecycle. A member joining mid-cycle receives the current allocation when the membership is provisioned, and the next workspace renewal recalculates everyone from the active plan.

Shared organization spending is gated by the workspace owner's team subscription. If the owner is too far beyond expiry, members cannot continue spending from workspace balance.

The grace window is controlled by TOKENS_NATURAL_EXPIRY_GRACE_HOURS. After that window, organization access follows ORGANIZATION_EXPIRY_MODE, which defaults to suspension and can be changed to dismantling.

Features are defined in lib/features.ts using the FeatureId enum. The shipped feature IDs (like WATERMARK_REMOVAL, FOV_ADJUST) are examples from the original product — replace them with your own.

export enum FeatureId {
  WATERMARK_REMOVAL = 'WATERMARK_REMOVAL',
  YOUR_FEATURE = 'YOUR_FEATURE',
  // Add your own feature IDs here
}

Wrap any UI that should be restricted to paid users in the FeatureGate server component:

import { FeatureGate } from '@/lib/featureGate';
import { FeatureId } from '@/lib/features';

<FeatureGate feature={FeatureId.YOUR_FEATURE}>
  <YourPremiumComponent />
</FeatureGate>

Content inside the gate is only rendered when the current user has an active subscription (personal or via team membership) that grants access to the specified feature.

In practical terms, use this for things like premium export buttons, advanced settings panels, or entire paid-only dashboard sections.

For server-side logic (API routes, server components), use isProFeature() to check feature access without rendering a component:

import { isProFeature } from '@/lib/features';

const hasAccess = await isProFeature(userId, FeatureId.YOUR_FEATURE);

This is the safer choice for API routes, server actions, and background jobs, because it protects the actual operation instead of only hiding the button that triggers it.