@flaghoist/core 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -20,16 +20,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FLAG_AUDIT_ACTIONS: () => FLAG_AUDIT_ACTIONS,
   FLAG_KEY_RULE: () => FLAG_KEY_RULE,
   FORBIDDEN_ATTRIBUTES: () => FORBIDDEN_ATTRIBUTES,
   LIMITS: () => LIMITS,
+  MEMBER_WEBHOOK_EVENTS: () => MEMBER_WEBHOOK_EVENTS,
+  WEBHOOK_EVENTS: () => WEBHOOK_EVENTS,
+  assertRecordAddress: () => assertRecordAddress,
+  auditCategory: () => auditCategory,
   clampPercentage: () => clampPercentage,
   compareSemver: () => compareSemver,
   createFlag: () => createFlag,
   evaluate: () => evaluate,
   evaluateAll: () => evaluateAll,
   isInRollout: () => isInRollout,
+  isValidCollectionName: () => isValidCollectionName,
   isValidFlagKey: () => isValidFlagKey,
+  isValidRecordId: () => isValidRecordId,
   matchCondition: () => matchCondition,
   matchesAllConditions: () => matchesAllConditions,
   parseFlag: () => parseFlag,
@@ -37,6 +44,33 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types.ts
+var FLAG_AUDIT_ACTIONS = [
+  "create",
+  "update",
+  "delete",
+  "archive",
+  "restore"
+];
+function auditCategory(action) {
+  return FLAG_AUDIT_ACTIONS.includes(action) ? "flags" : "security";
+}
+var WEBHOOK_EVENTS = [
+  "flag.created",
+  "flag.updated",
+  "flag.deleted",
+  "flag.archived",
+  "flag.restored"
+];
+var MEMBER_WEBHOOK_EVENTS = [
+  "member.invited",
+  "member.joined",
+  "member.role_changed",
+  "member.disabled",
+  "member.enabled",
+  "member.removed"
+];
+
 // src/hash.ts
 function clampPercentage(percentage) {
   if (Number.isNaN(percentage)) return 0;
@@ -74,6 +108,31 @@ function isValidFlagKey(key) {
   return key.length >= 1 && key.length <= LIMITS.maxKeyLength && FLAG_KEY_PATTERN.test(key);
 }
 var FLAG_KEY_RULE = "must be 1-256 characters of [A-Za-z0-9._-] and start with an alphanumeric";
+var COLLECTION_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+function isValidCollectionName(name) {
+  return COLLECTION_NAME_PATTERN.test(name);
+}
+var MAX_RECORD_ID_BYTES = 256;
+function isValidRecordId(id) {
+  if (id.length < 1 || new TextEncoder().encode(id).length > MAX_RECORD_ID_BYTES) return false;
+  for (let i = 0; i < id.length; i++) {
+    const code = id.charCodeAt(i);
+    if (code < 32 || code === 127) return false;
+  }
+  return true;
+}
+function assertRecordAddress(collection, id) {
+  if (!isValidCollectionName(collection)) {
+    throw new Error(
+      `Invalid record collection ${JSON.stringify(collection)}: must match ${COLLECTION_NAME_PATTERN.source}.`
+    );
+  }
+  if (id !== void 0 && !isValidRecordId(id)) {
+    throw new Error(
+      `Invalid record id: must be 1-${MAX_RECORD_ID_BYTES} bytes with no control characters.`
+    );
+  }
+}
 
 // src/operators.ts
 function isScalar(v) {
@@ -151,6 +210,7 @@ async function resolveRule(result, targetingKey, flagKey, ruleIndex) {
   return { value, reason: isSplit(percentage) ? "SPLIT" : "TARGETING_MATCH", ruleIndex };
 }
 async function evaluate(flag, context = {}) {
+  if (flag.archived) return { value: false, reason: "DISABLED" };
   if (!flag.enabled) return { value: false, reason: "DISABLED" };
   const targetingKey = context.targetingKey ?? "";
   let ruleIndex = 0;
@@ -256,7 +316,7 @@ function parseFlag(input) {
   const rawRules = Array.isArray(o.rules) ? o.rules : [];
   if (rawRules.length > LIMITS.maxRules) return null;
   const rules = rawRules.map(parseRule).filter((r) => r !== null);
-  return {
+  const flag = {
     key: o.key,
     enabled: o.enabled,
     rollout: { percentage },
@@ -264,6 +324,14 @@ function parseFlag(input) {
     description: typeof o.description === "string" ? o.description : "",
     metadata: parseMetadata(o.metadata)
   };
+  if (o.archived === true) {
+    flag.archived = true;
+    if (typeof o.archivedAt === "string") flag.archivedAt = o.archivedAt;
+  }
+  if (typeof o.environment === "string" && o.environment.length > 0) {
+    flag.environment = o.environment;
+  }
+  return flag;
 }
 function createFlag(input) {
   if (!isValidFlagKey(input.key)) {
@@ -282,16 +350,23 @@ function createFlag(input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FLAG_AUDIT_ACTIONS,
   FLAG_KEY_RULE,
   FORBIDDEN_ATTRIBUTES,
   LIMITS,
+  MEMBER_WEBHOOK_EVENTS,
+  WEBHOOK_EVENTS,
+  assertRecordAddress,
+  auditCategory,
   clampPercentage,
   compareSemver,
   createFlag,
   evaluate,
   evaluateAll,
   isInRollout,
+  isValidCollectionName,
   isValidFlagKey,
+  isValidRecordId,
   matchCondition,
   matchesAllConditions,
   parseFlag,

package/dist/index.d.cts

@@ -50,6 +50,14 @@ interface FeatureFlag {
     rules?: TargetingRule[];
     description: string;
     metadata: FlagMetadata;
+    archived?: boolean;
+    archivedAt?: string;
+    /**
+     * The environment this flag belongs to, when the server has environments configured. Absent
+     * means the default environment ("production"), so existing bare-keyed flags need no migration
+     * when environments are turned on for the first time.
+     */
+    environment?: string;
 }
 /**
  * The OpenFeature-style evaluation context: an optional stable `targetingKey` used for
@@ -76,6 +84,114 @@ interface StorageAdapter {
     put(key: string, flag: FeatureFlag): Promise<void>;
     delete(key: string): Promise<void>;
     list(): Promise<FeatureFlag[]>;
+    /** Append an audit entry to persistent storage. Optional; the server falls back to in-memory. */
+    appendAudit?(entry: AuditEntry): Promise<void>;
+    /** List audit entries with optional filtering and pagination. */
+    listAudit?(options?: AuditListOptions): Promise<AuditPage>;
+    /** Store a webhook endpoint. Optional; the server falls back to in-memory. */
+    putWebhook?(id: string, webhook: WebhookEndpoint): Promise<void>;
+    /** Retrieve a webhook by id. */
+    getWebhook?(id: string): Promise<WebhookEndpoint | null>;
+    /** Remove a webhook. */
+    deleteWebhook?(id: string): Promise<void>;
+    /** List all webhook endpoints. */
+    listWebhooks?(): Promise<WebhookEndpoint[]>;
+    /**
+     * Generic record store: JSON values grouped into named collections, addressed by id. Optional.
+     * Features that need persistent server-side state beyond flags build on this rather than adding
+     * a new method group to every adapter. Collection names must pass `isValidCollectionName` and
+     * ids `isValidRecordId`; values must be JSON-serializable.
+     */
+    getRecord?(collection: string, id: string): Promise<unknown | null>;
+    /** Create or replace a record. */
+    putRecord?(collection: string, id: string, value: unknown): Promise<void>;
+    /** Remove a record. Removing a missing record is a no-op. */
+    deleteRecord?(collection: string, id: string): Promise<void>;
+    /** List every record in one collection, in no particular order. */
+    listRecords?(collection: string): Promise<RecordEntry[]>;
+}
+/** One record returned by `StorageAdapter.listRecords`. */
+interface RecordEntry {
+    id: string;
+    value: unknown;
+}
+/** A point-in-time snapshot of a flag's evaluable state, recorded in audit entries. */
+interface FlagSnapshot {
+    enabled: boolean;
+    rollout: {
+        percentage: number;
+    };
+    description: string;
+}
+/** Actions recorded against a flag. */
+type FlagAuditAction = 'create' | 'update' | 'delete' | 'archive' | 'restore';
+/**
+ * Actions recorded against accounts, sessions and webhooks. These never carry a `flagKey`; they
+ * name what they touched in `target` instead.
+ */
+type SecurityAuditAction = 'login' | 'login.failed' | 'logout' | 'password.changed' | 'session.revoked' | 'password.reset' | 'user.created' | 'user.updated' | 'user.removed' | 'invite.created' | 'invite.accepted' | 'invite.revoked' | 'token.created' | 'token.revoked' | 'token.expired' | 'two_factor.enabled' | 'two_factor.disabled' | 'two_factor.reset' | 'two_factor.recovery_used' | 'webhook.created' | 'webhook.updated' | 'webhook.deleted';
+type AuditAction = FlagAuditAction | SecurityAuditAction;
+declare const FLAG_AUDIT_ACTIONS: readonly FlagAuditAction[];
+/** Which log an entry belongs to: flag changes, or sign-ins and configuration changes. */
+type AuditCategory = 'flags' | 'security';
+declare function auditCategory(action: AuditAction): AuditCategory;
+/** What a security event touched. */
+interface AuditTarget {
+    type: 'user' | 'session' | 'invite' | 'token' | 'webhook';
+    id: string;
+}
+interface AuditEntry {
+    id: string;
+    timestamp: string;
+    action: AuditAction;
+    /** The flag that changed. Always set on flag events; absent on security events. */
+    flagKey?: string;
+    /** What a security event touched. Absent on flag events. */
+    target?: AuditTarget;
+    actor: string;
+    previous?: FlagSnapshot;
+    current?: FlagSnapshot;
+    /** A note on the change: the author's description on flag events, context on security events. */
+    changeDescription?: string;
+    /** The environment the change happened in. Absent means the default environment. */
+    environment?: string;
+}
+interface AuditListOptions {
+    limit?: number;
+    offset?: number;
+    /**
+     * Which log to read. Adapters that persist audit entries should honour this; `auditCategory()`
+     * maps an action onto its category. Absent means both.
+     */
+    category?: AuditCategory;
+    flagKey?: string;
+    action?: AuditAction;
+    /** Restrict to entries recorded in this environment. Absent means the default environment. */
+    environment?: string;
+}
+interface AuditPage {
+    entries: AuditEntry[];
+    total: number;
+}
+type FlagWebhookEvent = 'flag.created' | 'flag.updated' | 'flag.deleted' | 'flag.archived' | 'flag.restored';
+/**
+ * Team changes, for servers with user accounts. Opt-in: a webhook gets them only when it lists
+ * them, never through the default event list, so a receiver built for flag events never sees a
+ * payload of another shape.
+ */
+type MemberWebhookEvent = 'member.invited' | 'member.joined' | 'member.role_changed' | 'member.disabled' | 'member.enabled' | 'member.removed';
+type WebhookEvent = FlagWebhookEvent | MemberWebhookEvent;
+/** The flag events: what a webhook subscribes to when it names no events. */
+declare const WEBHOOK_EVENTS: FlagWebhookEvent[];
+declare const MEMBER_WEBHOOK_EVENTS: MemberWebhookEvent[];
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    secret: string;
+    events: WebhookEvent[];
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
 }
 /** The authenticated caller, extracted from a validated admin token. */
 interface AuthContext {
@@ -134,6 +250,20 @@ declare const FORBIDDEN_ATTRIBUTES: ReadonlySet<string>;
 declare function isValidFlagKey(key: string): boolean;
 /** Human-readable description of the flag key rule, for error messages. */
 declare const FLAG_KEY_RULE = "must be 1-256 characters of [A-Za-z0-9._-] and start with an alphanumeric";
+/**
+ * A record-store collection name. Collections are chosen by server code, never by callers, but
+ * adapters embed them in storage keys and table rows, so the charset stays narrow: lowercase
+ * alphanumerics and hyphens, no separators that could collide with an adapter's key layout.
+ */
+declare function isValidCollectionName(name: string): boolean;
+/**
+ * A record id. Ids can carry user-supplied text (an email address used as a lookup key, say), so
+ * they allow any printable characters but must be non-empty, bounded, and free of control
+ * characters.
+ */
+declare function isValidRecordId(id: string): boolean;
+/** Throw if a collection name or record id is not safe to hand to a storage adapter. */
+declare function assertRecordAddress(collection: string, id?: string): void;
 
 /**
  * Compare two semver strings. Returns -1, 0, or 1. A version with no prerelease outranks
@@ -186,4 +316,4 @@ interface CreateFlagInput {
  */
 declare function createFlag(input: CreateFlagInput): FeatureFlag;
 
-export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket };
+export { type AttributeValue, type AuditAction, type AuditCategory, type AuditEntry, type AuditListOptions, type AuditPage, type AuditTarget, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_AUDIT_ACTIONS, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagAuditAction, type FlagMetadata, type FlagSnapshot, type FlagWebhookEvent, LIMITS, MEMBER_WEBHOOK_EVENTS, type MemberWebhookEvent, type Operator, type RecordEntry, type RuleResult, type SecurityAuditAction, type StorageAdapter, type TargetingRule, WEBHOOK_EVENTS, type WebhookEndpoint, type WebhookEvent, assertRecordAddress, auditCategory, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidCollectionName, isValidFlagKey, isValidRecordId, matchCondition, matchesAllConditions, parseFlag, stickyBucket };

package/dist/index.d.ts

@@ -50,6 +50,14 @@ interface FeatureFlag {
     rules?: TargetingRule[];
     description: string;
     metadata: FlagMetadata;
+    archived?: boolean;
+    archivedAt?: string;
+    /**
+     * The environment this flag belongs to, when the server has environments configured. Absent
+     * means the default environment ("production"), so existing bare-keyed flags need no migration
+     * when environments are turned on for the first time.
+     */
+    environment?: string;
 }
 /**
  * The OpenFeature-style evaluation context: an optional stable `targetingKey` used for
@@ -76,6 +84,114 @@ interface StorageAdapter {
     put(key: string, flag: FeatureFlag): Promise<void>;
     delete(key: string): Promise<void>;
     list(): Promise<FeatureFlag[]>;
+    /** Append an audit entry to persistent storage. Optional; the server falls back to in-memory. */
+    appendAudit?(entry: AuditEntry): Promise<void>;
+    /** List audit entries with optional filtering and pagination. */
+    listAudit?(options?: AuditListOptions): Promise<AuditPage>;
+    /** Store a webhook endpoint. Optional; the server falls back to in-memory. */
+    putWebhook?(id: string, webhook: WebhookEndpoint): Promise<void>;
+    /** Retrieve a webhook by id. */
+    getWebhook?(id: string): Promise<WebhookEndpoint | null>;
+    /** Remove a webhook. */
+    deleteWebhook?(id: string): Promise<void>;
+    /** List all webhook endpoints. */
+    listWebhooks?(): Promise<WebhookEndpoint[]>;
+    /**
+     * Generic record store: JSON values grouped into named collections, addressed by id. Optional.
+     * Features that need persistent server-side state beyond flags build on this rather than adding
+     * a new method group to every adapter. Collection names must pass `isValidCollectionName` and
+     * ids `isValidRecordId`; values must be JSON-serializable.
+     */
+    getRecord?(collection: string, id: string): Promise<unknown | null>;
+    /** Create or replace a record. */
+    putRecord?(collection: string, id: string, value: unknown): Promise<void>;
+    /** Remove a record. Removing a missing record is a no-op. */
+    deleteRecord?(collection: string, id: string): Promise<void>;
+    /** List every record in one collection, in no particular order. */
+    listRecords?(collection: string): Promise<RecordEntry[]>;
+}
+/** One record returned by `StorageAdapter.listRecords`. */
+interface RecordEntry {
+    id: string;
+    value: unknown;
+}
+/** A point-in-time snapshot of a flag's evaluable state, recorded in audit entries. */
+interface FlagSnapshot {
+    enabled: boolean;
+    rollout: {
+        percentage: number;
+    };
+    description: string;
+}
+/** Actions recorded against a flag. */
+type FlagAuditAction = 'create' | 'update' | 'delete' | 'archive' | 'restore';
+/**
+ * Actions recorded against accounts, sessions and webhooks. These never carry a `flagKey`; they
+ * name what they touched in `target` instead.
+ */
+type SecurityAuditAction = 'login' | 'login.failed' | 'logout' | 'password.changed' | 'session.revoked' | 'password.reset' | 'user.created' | 'user.updated' | 'user.removed' | 'invite.created' | 'invite.accepted' | 'invite.revoked' | 'token.created' | 'token.revoked' | 'token.expired' | 'two_factor.enabled' | 'two_factor.disabled' | 'two_factor.reset' | 'two_factor.recovery_used' | 'webhook.created' | 'webhook.updated' | 'webhook.deleted';
+type AuditAction = FlagAuditAction | SecurityAuditAction;
+declare const FLAG_AUDIT_ACTIONS: readonly FlagAuditAction[];
+/** Which log an entry belongs to: flag changes, or sign-ins and configuration changes. */
+type AuditCategory = 'flags' | 'security';
+declare function auditCategory(action: AuditAction): AuditCategory;
+/** What a security event touched. */
+interface AuditTarget {
+    type: 'user' | 'session' | 'invite' | 'token' | 'webhook';
+    id: string;
+}
+interface AuditEntry {
+    id: string;
+    timestamp: string;
+    action: AuditAction;
+    /** The flag that changed. Always set on flag events; absent on security events. */
+    flagKey?: string;
+    /** What a security event touched. Absent on flag events. */
+    target?: AuditTarget;
+    actor: string;
+    previous?: FlagSnapshot;
+    current?: FlagSnapshot;
+    /** A note on the change: the author's description on flag events, context on security events. */
+    changeDescription?: string;
+    /** The environment the change happened in. Absent means the default environment. */
+    environment?: string;
+}
+interface AuditListOptions {
+    limit?: number;
+    offset?: number;
+    /**
+     * Which log to read. Adapters that persist audit entries should honour this; `auditCategory()`
+     * maps an action onto its category. Absent means both.
+     */
+    category?: AuditCategory;
+    flagKey?: string;
+    action?: AuditAction;
+    /** Restrict to entries recorded in this environment. Absent means the default environment. */
+    environment?: string;
+}
+interface AuditPage {
+    entries: AuditEntry[];
+    total: number;
+}
+type FlagWebhookEvent = 'flag.created' | 'flag.updated' | 'flag.deleted' | 'flag.archived' | 'flag.restored';
+/**
+ * Team changes, for servers with user accounts. Opt-in: a webhook gets them only when it lists
+ * them, never through the default event list, so a receiver built for flag events never sees a
+ * payload of another shape.
+ */
+type MemberWebhookEvent = 'member.invited' | 'member.joined' | 'member.role_changed' | 'member.disabled' | 'member.enabled' | 'member.removed';
+type WebhookEvent = FlagWebhookEvent | MemberWebhookEvent;
+/** The flag events: what a webhook subscribes to when it names no events. */
+declare const WEBHOOK_EVENTS: FlagWebhookEvent[];
+declare const MEMBER_WEBHOOK_EVENTS: MemberWebhookEvent[];
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    secret: string;
+    events: WebhookEvent[];
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
 }
 /** The authenticated caller, extracted from a validated admin token. */
 interface AuthContext {
@@ -134,6 +250,20 @@ declare const FORBIDDEN_ATTRIBUTES: ReadonlySet<string>;
 declare function isValidFlagKey(key: string): boolean;
 /** Human-readable description of the flag key rule, for error messages. */
 declare const FLAG_KEY_RULE = "must be 1-256 characters of [A-Za-z0-9._-] and start with an alphanumeric";
+/**
+ * A record-store collection name. Collections are chosen by server code, never by callers, but
+ * adapters embed them in storage keys and table rows, so the charset stays narrow: lowercase
+ * alphanumerics and hyphens, no separators that could collide with an adapter's key layout.
+ */
+declare function isValidCollectionName(name: string): boolean;
+/**
+ * A record id. Ids can carry user-supplied text (an email address used as a lookup key, say), so
+ * they allow any printable characters but must be non-empty, bounded, and free of control
+ * characters.
+ */
+declare function isValidRecordId(id: string): boolean;
+/** Throw if a collection name or record id is not safe to hand to a storage adapter. */
+declare function assertRecordAddress(collection: string, id?: string): void;
 
 /**
  * Compare two semver strings. Returns -1, 0, or 1. A version with no prerelease outranks
@@ -186,4 +316,4 @@ interface CreateFlagInput {
  */
 declare function createFlag(input: CreateFlagInput): FeatureFlag;
 
-export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket };
+export { type AttributeValue, type AuditAction, type AuditCategory, type AuditEntry, type AuditListOptions, type AuditPage, type AuditTarget, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_AUDIT_ACTIONS, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagAuditAction, type FlagMetadata, type FlagSnapshot, type FlagWebhookEvent, LIMITS, MEMBER_WEBHOOK_EVENTS, type MemberWebhookEvent, type Operator, type RecordEntry, type RuleResult, type SecurityAuditAction, type StorageAdapter, type TargetingRule, WEBHOOK_EVENTS, type WebhookEndpoint, type WebhookEvent, assertRecordAddress, auditCategory, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidCollectionName, isValidFlagKey, isValidRecordId, matchCondition, matchesAllConditions, parseFlag, stickyBucket };

package/dist/index.js

@@ -1,3 +1,30 @@
+// src/types.ts
+var FLAG_AUDIT_ACTIONS = [
+  "create",
+  "update",
+  "delete",
+  "archive",
+  "restore"
+];
+function auditCategory(action) {
+  return FLAG_AUDIT_ACTIONS.includes(action) ? "flags" : "security";
+}
+var WEBHOOK_EVENTS = [
+  "flag.created",
+  "flag.updated",
+  "flag.deleted",
+  "flag.archived",
+  "flag.restored"
+];
+var MEMBER_WEBHOOK_EVENTS = [
+  "member.invited",
+  "member.joined",
+  "member.role_changed",
+  "member.disabled",
+  "member.enabled",
+  "member.removed"
+];
+
 // src/hash.ts
 function clampPercentage(percentage) {
   if (Number.isNaN(percentage)) return 0;
@@ -35,6 +62,31 @@ function isValidFlagKey(key) {
   return key.length >= 1 && key.length <= LIMITS.maxKeyLength && FLAG_KEY_PATTERN.test(key);
 }
 var FLAG_KEY_RULE = "must be 1-256 characters of [A-Za-z0-9._-] and start with an alphanumeric";
+var COLLECTION_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+function isValidCollectionName(name) {
+  return COLLECTION_NAME_PATTERN.test(name);
+}
+var MAX_RECORD_ID_BYTES = 256;
+function isValidRecordId(id) {
+  if (id.length < 1 || new TextEncoder().encode(id).length > MAX_RECORD_ID_BYTES) return false;
+  for (let i = 0; i < id.length; i++) {
+    const code = id.charCodeAt(i);
+    if (code < 32 || code === 127) return false;
+  }
+  return true;
+}
+function assertRecordAddress(collection, id) {
+  if (!isValidCollectionName(collection)) {
+    throw new Error(
+      `Invalid record collection ${JSON.stringify(collection)}: must match ${COLLECTION_NAME_PATTERN.source}.`
+    );
+  }
+  if (id !== void 0 && !isValidRecordId(id)) {
+    throw new Error(
+      `Invalid record id: must be 1-${MAX_RECORD_ID_BYTES} bytes with no control characters.`
+    );
+  }
+}
 
 // src/operators.ts
 function isScalar(v) {
@@ -112,6 +164,7 @@ async function resolveRule(result, targetingKey, flagKey, ruleIndex) {
   return { value, reason: isSplit(percentage) ? "SPLIT" : "TARGETING_MATCH", ruleIndex };
 }
 async function evaluate(flag, context = {}) {
+  if (flag.archived) return { value: false, reason: "DISABLED" };
   if (!flag.enabled) return { value: false, reason: "DISABLED" };
   const targetingKey = context.targetingKey ?? "";
   let ruleIndex = 0;
@@ -217,7 +270,7 @@ function parseFlag(input) {
   const rawRules = Array.isArray(o.rules) ? o.rules : [];
   if (rawRules.length > LIMITS.maxRules) return null;
   const rules = rawRules.map(parseRule).filter((r) => r !== null);
-  return {
+  const flag = {
     key: o.key,
     enabled: o.enabled,
     rollout: { percentage },
@@ -225,6 +278,14 @@ function parseFlag(input) {
     description: typeof o.description === "string" ? o.description : "",
     metadata: parseMetadata(o.metadata)
   };
+  if (o.archived === true) {
+    flag.archived = true;
+    if (typeof o.archivedAt === "string") flag.archivedAt = o.archivedAt;
+  }
+  if (typeof o.environment === "string" && o.environment.length > 0) {
+    flag.environment = o.environment;
+  }
+  return flag;
 }
 function createFlag(input) {
   if (!isValidFlagKey(input.key)) {
@@ -242,16 +303,23 @@ function createFlag(input) {
   };
 }
 export {
+  FLAG_AUDIT_ACTIONS,
   FLAG_KEY_RULE,
   FORBIDDEN_ATTRIBUTES,
   LIMITS,
+  MEMBER_WEBHOOK_EVENTS,
+  WEBHOOK_EVENTS,
+  assertRecordAddress,
+  auditCategory,
   clampPercentage,
   compareSemver,
   createFlag,
   evaluate,
   evaluateAll,
   isInRollout,
+  isValidCollectionName,
   isValidFlagKey,
+  isValidRecordId,
   matchCondition,
   matchesAllConditions,
   parseFlag,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Flag schema, evaluation engine, and storage/auth interfaces for Flaghoist. Zero dependencies.",
   "license": "Apache-2.0",
   "type": "module",