Entitlements - Nozle

import { Nozle } from '@nozle-js/node'

const nozle = new Nozle() // reads NOZLE_SECRET_KEY

const check = await nozle.can('workspace_123', 'api_calls')

if (!check.allowed) {
  throw new Error(check.reason ?? 'Feature unavailable')
}

can() calls GET /api/v1/can with the customer, feature, and optional metadata. Metadata is input to the cost and margin estimate only (Cost Sheet conditions and quantities). It does not filter usage: used, limit and remaining always cover all of the feature’s usage, whatever model or other properties you send.

Signature

import type { CanResult } from '@nozle-js/node'

can(
  customerId: string,
  feature: string,
  metadata?: Record<string, string>,
): Promise<CanResult>

const check = await nozle.can('workspace_123', 'model_access', {
  model: 'example-large-model',
  region: 'us-east',
})

`CanResult`

Field	Type	Description
`allowed`	`boolean`	Whether the request may proceed.
`feature_type`	`string?`	Type of the feature.
`reason`	`string?`	Denial or decision reason. Present only when it applies.
`used`	`number`	Current measured usage.
`limit`	`number \| null`	Configured usage limit. `null` when the feature has no limit.
`remaining`	`number \| null`	Remaining allowance. `null` when the feature has no limit.
`overage`	`boolean?`	`true` when usage has reached a soft limit; the usage is billed as overage. Never a denial by itself. Present only when it applies.
`policy`	`object?`	Configured policy. Present only when configured.
`configuration`	`Record<string, string>?`	Feature configuration. Present only when configured.
`economics`	`object?`	Point-in-time Cost Sheet estimate with exact decimal strings, Cost Rule version identifiers, and explicit exclusions.

economics contains:

Field	Description
`status`	Estimate status, for example `not_configured`.
`estimated_incremental_revenue`	Estimated incremental revenue.
`includes`	What the estimate includes.
`excludes`	What the estimate excludes.
`reason`	Why the estimate has its status, for example `missing_cost_composition`.
`calculated_at`	When the estimate was calculated.

HTTP handler pattern

const check = await nozle.can(customerId, 'analytics')

if (!check.allowed) {
  return Response.json(
    {
      error: check.reason ?? 'upgrade_required',
      used: check.used,
      limit: check.limit,
      remaining: check.remaining,
    },
    { status: 403 },
  )
}

if (check.overage) {
  // Allowed: a soft limit is reached, so this usage is billed as overage.
  warnAboutOverage(customerId, check)
}

return runAnalyticsQuery()

Deny only when allowed is false. overage: true never denies by itself: a soft limit is reached and the usage is billed as overage.

Authorization guidance

Perform entitlement checks on the trusted backend immediately before protected work. A React FeatureGate improves the interface but is not an authorization boundary. can() checks entitlement and usage state; it does not reserve product credits. Use usage.track() for atomic credit-backed consumption.