Gates

A gate is a single boolean answer for a single user. It is the unit of "should I do the new thing?" in your code. Gates are evaluated locally — the SDK keeps the bundle in process and the call is a hash table lookup, not a network round trip.

Use a gate when the answer is yes/no. For typed payloads (strings, numbers, JSON), reach for a dynamic value. For yes/no with measurement attached, reach for an experiment.

Anatomy of a gate

Evaluation order

For a request gate(name, user):

1. killswitch ON                       → false
2. enabled OFF                         → false
3. user.user_id ∈ overrides[true]      → true
4. user.user_id ∈ overrides[false]     → false
5. any rule fails                      → false
6. murmur3(salt + user_id) % 10000 < rolloutPct → true
7. otherwise                           → false

That order matters: rules are evaluated before the rollout. "100% of plan = pro" means 100% of pro users, not the same 100% bucket filtered down to pros. The rollout filter never fights a targeting rule.

API

Server SDK

import { configureShipeasy, flags } from "@shipeasy/sdk/server";

configureShipeasy({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
await flags.init();

const enabled = flags.gate("new-checkout-flow", {
  user_id: "u_4f2a",
  plan: "pro",
  country: "US",
});

Browser SDK

import { configureShipeasy } from "@shipeasy/sdk/client";

const client = configureShipeasy({ apiKey });
await client.identify({ user_id, plan, country });

if (client.getFlag("new-checkout-flow")) {
  // …
}

gate() / getFlag() is synchronous. If you call it before init() resolves, you get false and a dev-mode warning. Always await flags.init() once at boot.

The return is a plain boolean. There is no async, no Promise, no fetch — the bundle is in memory.

Killswitch

The killswitch is a separate field from enabled so you can keep targeting and rollout intact while turning the feature off. Three places to flip it:

• Dashboard: red Killswitch chip on the gate row.
• CLI: shipeasy flags disable <name> --killswitch (without --killswitch it toggles enabled instead).
• API: PATCH /api/flags/<name> with { "killswitch": true }.

A killed gate returns false everywhere within the SDK's next poll. Re-enabling restores the full prior state — overrides, rules, rollout %, salt, all of it. Treat the killswitch as your incident lever; treat enabled as your "feature is shipped, deactivated cleanly" lever.

Overrides

In the dashboard, expand a gate and add user IDs under Overrides → Always on or Always off. Overrides:

• Bypass enabled, killswitch, all rules, and the rollout.
• Are scoped to user_id only (no attribute matching — it's a literal set lookup).
• Are great for: QA accounts, internal dogfooders, customer-success demos, repro of a bug a single customer is hitting.

// dashboard JSON shape:
{
  "name": "new-checkout-flow",
  "overrides": {
    "always_on":  ["u_qa1", "u_qa2", "u_demo"],
    "always_off": ["u_legacy_partner"]
  }
}

If you need a percentage-based "always-on for cohort X", use a targeting rule on a custom attribute (internal: true) instead. Overrides scale linearly per-row in KV; rules are O(1).

Naming

• kebab-case: new-checkout-flow, not newCheckoutFlow.
• Describe the change, not the abstract feature: enable-redis-pool ages better than redis-pool (which sounds like a permanent feature, not a temporary gate).
• Prefix by area for grouping: checkout-, nav-, infra-.
• Avoid double-negatives: prefer show-banner over hide-banner.

Cleaning up

Stale flags are technical debt — once a feature is fully launched, delete the flag and the dead code. The CLI helps:

# Every gate currently at enabled: true, rollout: 100%
shipeasy flags list --json \
  | jq '.[] | select(.enabled == 1 and .rolloutPct == 10000) | .name'

These are candidates for removal. Run a shipeasy flags validate ./src after the deletion to catch any code references that need to be ripped out.

The dashboard also surfaces a Cleanup view that lists gates which have been at 100% (or 0%) for more than 30 days, with a one-click PR-creation button if you've connected a GitHub app.

The salt

Each gate has its own salt. If you ever want to re-shuffle the rollout buckets without changing the percentage (say, to avoid the same 5% always being chosen for every gate), bump the salt:

shipeasy flags update my-feature --salt v2

That's rare. The default salt is fine for almost every case. The salt is also why two gates at 50% don't serve the same 50% of users — different salts, different buckets, independently distributed.

Audit log

Every write to a gate is recorded in the audit log: who, when, from what (dashboard, CLI, API), and the diff. Find it under Configs → Gates → <gate> → History. Each row links to a one-click revert.

Limits

If you hit a limit, audit for stale flags first; those numbers are very generous if you delete what you ship.