# `plandalf.gate()`

Check access and present its fallback offer when needed.

Implemented by the [browser object](https://github.com/plandalf/numi/blob/fc6f42b5ade3d63b71623934838a6509f17203e2/packages/sdk/src/browser.ts#L446); parameter and return types follow the [delegated class declaration](https://github.com/plandalf/numi/blob/fc6f42b5ade3d63b71623934838a6509f17203e2/packages/sdk/src/core/sdk.ts#L396).

Call this after `plandalf.ready()`. The browser wrapper can return `undefined` before initialization.

## Signature

```typescript
plandalf.gate(
  name: string,
  sync?: GateSyncCallback,
  opts?: Partial<FlowOpenOptions>,
): Promise<GateResult>
```

## Arguments

| Name | Type | Meaning |
| --- | --- | --- |
| `name` | `string` | Name registered with `addGate()`. |
| `sync?` | [`GateSyncCallback`](https://plandalf.com/docs/packages/sdk/type-aliases/GateSyncCallback) | Optional callback to refresh entitlements after purchase. The browser wrapper declares this argument as `any` and passes it to the typed class method. |
| `opts?` | `Partial`\<[`FlowOpenOptions`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions)\> | Flow options for the fallback offer. The browser wrapper declares this argument as `any` and passes it to the typed class method. |

## Example

```javascript title="gate.js" lineNumbers lineNumberStart=1
plandalf.ready(async () => {
  plandalf.addGate('export', 'upgrade', () => false)
  const result = await plandalf.gate('export')
  if (result.access) {
    // Ask your server to perform the protected action.
  }
})
```

## Fallback flow options

The `opts` object accepts these [`FlowOpenOptions`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions) fields.

| Field | Type | Meaning |
| --- | --- | --- |
| [`confirmClose?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#confirmclose) | () => `boolean` \| `Promise`\<`boolean`\> | Merchant-supplied "are you sure?" gate. Resolved `true` allows the close to proceed, `false` keeps the frame open. Replaces the previous boolean \+ label/title strings combo. Off when omitted. |
| [`context?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#context) | `Record`\<`string`, `unknown`\> | Initial values for the flow context. |
| [`continuity?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#continuity) | [`ContinuityScope`](https://plandalf.com/docs/packages/sdk/referenced-types/ContinuityScope) | Per-call continuity override. |
| [`frame?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#frame) | [`FrameMode`](https://plandalf.com/docs/packages/sdk/type-aliases/FrameMode) | Frame modality. Was previously `mode` — renamed because `mode` now means the test/live/preview environment (see below). |
| [`metadata?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#metadata) | `Record`\<`string`, `string`\> | Per-call Stripe-customer metadata. Eager string values only — for window-global lookups use the page-global PlandalfConfig.metadata thunk form. Wins over PlandalfConfig.metadata on overlap. |
| [`mode?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#mode) | `"test"` \| `"live"` \| `"preview"` | Environment override: 'test' \| 'live' \| 'preview'. Was previously `environment`. The server uses this to route the session through the org's test or live integration; super-admin only. |
| [`promo?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#promo) | [`PromoContext`](https://plandalf.com/docs/packages/sdk/interfaces/PromoContext) | Resolved promotion context. The current `present()` implementation also resolves a promo slug string at runtime. |
| [`properties?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#properties) | `Record`\<`string`, `unknown`\> | Per-call form-field prefill defaults. Wins over PlandalfConfig.properties on overlap. See specs/sdk-checkout-config.md. |
| [`session?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#session) | `string` \| `null` | Session continuity token (`cks_…`). Pass explicitly to resume a specific session server-side — cross-device handoff, email "continue your checkout" links, anywhere the merchant has a token in hand. Pass `null` to force a fresh session and skip any stored token. Omit entirely to let the SDK auto-detect. |
| [`sessionId?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#sessionid) | `string` | Reuse an existing session UUID instead of creating a fresh one. Used by the auto-resume path to finalize against the ORIGINAL session after a redirect-based auth bounce — creating a new session would lose the draft upsell invoice that needs settling. |
| [`size?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#size) | [`FlowSize`](https://plandalf.com/docs/packages/sdk/referenced-types/FlowSize) \| \{ `h`: `string`; `w`: `string`; \} | Size of the modal panel. Either a named preset OR an explicit `{ w, h }` object for one-off cases. Defaults to 'standard'. |
| [`templateId?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#templateid) | `string` | Lower-level template selector. The method supplies `templateSlug` from its slug argument, so this does not select the offer here. |
| [`templateSlug?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#templateslug) | `string` | Can override the slug argument in the current implementation. Pass the desired slug as the method argument instead. |
| [`user?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#user) | `string` | Customer JWT for THIS call only — overrides the SDK-wide identity from `plandalf.setUser()` or the `user` init option. Useful for "buy as customer" admin tooling, impersonation flows, or offers that need a different identity than the global one. The value is the raw JWT string. |

### Supported compatibility options

The current runtime still reads these older fields.

| Field | Type | Meaning |
| --- | --- | --- |
| [`animation?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#animation) | `"slide"` \| `"fade"` \| `"none"` | Frame entrance animation. |
| [`backdrop?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#backdrop) | `boolean` | Whether to render a backdrop behind the frame. |
| [`closeButton?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#closebutton) | `boolean` | Whether to show the frame close button. |
| [`closeOnBackdrop?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#closeonbackdrop) | `boolean` | Whether a backdrop click closes the frame. |
| [`confirmLeaveLabel?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#confirmleavelabel) | `string` | Leave button text in the built-in close confirmation. |
| [`confirmMessage?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#confirmmessage) | `string` | Message in the built-in close confirmation. |
| [`confirmStayLabel?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#confirmstaylabel) | `string` | Stay button text in the built-in close confirmation. |
| [`confirmTitle?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#confirmtitle) | `string` | Title in the built-in close confirmation. |
| [`duration?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#duration) | `number` | Frame animation duration in milliseconds. |
| [`environment?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#environment) | `"test"` \| `"live"` | Test or live session routing. The newer per-call name is `mode`. |
| [`height?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#height) | `string` | Explicit frame height. |
| [`onClose?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#onclose) | (`reason`) => `void` | Callback when the presented flow closes. Await the handle for the final result. |
| [`onComplete?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#oncomplete) | (`result`) => `void` | Callback on flow completion. Await the handle for the final result. |
| [`onError?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#onerror) | (`error`) => `void` | Callback on flow failure. A rejected handle can also be caught. |
| [`position?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#position) | `"left"` \| `"right"` | Frame position, left or right. |
| [`width?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#width) | `string` | Explicit frame width. This takes precedence over a size preset. |

### Declared without current effect

| Field | Type | Meaning |
| --- | --- | --- |
| [`dragToClose?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#dragtoclose) | `boolean` | Collected into frame config, but not passed to the rendered frame. |
| [`headless?`](https://plandalf.com/docs/packages/sdk/interfaces/FlowOpenOptions#headless) | `boolean` | Declared in the type, but the checkout implementation does not read it. |

## Returns

`Promise`\<[`GateResult`](https://plandalf.com/docs/packages/sdk/interfaces/GateResult)\>

## Behaviour

The `sync` callback can refresh entitlements after purchase. The returned `GateResult` describes whether access was granted.

[All plandalf methods](https://plandalf.com/docs/sdk)

Source: https://plandalf.com/docs/sdk/gate