@revturbine/sdk 0.7.1 → 0.7.3

package/dist/growthbook.d.ts

@@ -0,0 +1,298 @@
+import { GrowthBook } from '@growthbook/growthbook';
+import { toJSONSchema, JSONSchemaMeta } from 'zod/v4/core';
+
+type OverrideParameters = Parameters<NonNullable<NonNullable<Parameters<typeof toJSONSchema>[1]>['override']>>[0];
+type OverrideSchemaParameters = Omit<OverrideParameters, 'zodSchema'>;
+type IExtensionType = any;
+type ISpecificationExtension = {
+  [extensionName: IExtensionName]: IExtensionType;
+};
+interface ExternalDocumentationObject extends ISpecificationExtension {
+  description?: string;
+  url: string;
+}
+type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+interface BaseParameterObject extends ISpecificationExtension {
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  style?: ParameterStyle;
+  explode?: boolean;
+  allowReserved?: boolean;
+  schema?: SchemaObject | ReferenceObject;
+  examples?: {
+    [param: string]: ExampleObject | ReferenceObject;
+  };
+  example?: any;
+  content?: ContentObject;
+}
+interface ParameterObject extends BaseParameterObject {
+  name: string;
+  in: ParameterLocation;
+}
+interface ContentObject {
+  [mediatype: string]: MediaTypeObject;
+}
+interface MediaTypeObject extends ISpecificationExtension {
+  schema?: SchemaObject | ReferenceObject;
+  examples?: ExamplesObject;
+  example?: any;
+  encoding?: EncodingObject;
+}
+interface EncodingObject extends ISpecificationExtension {
+  [property: string]: EncodingPropertyObject | any;
+}
+interface EncodingPropertyObject {
+  contentType?: string;
+  headers?: {
+    [key: string]: HeaderObject | ReferenceObject;
+  };
+  style?: string;
+  explode?: boolean;
+  allowReserved?: boolean;
+  [key: string]: any;
+}
+interface ExampleObject {
+  summary?: string;
+  description?: string;
+  value?: any;
+  externalValue?: string;
+  [property: string]: any;
+}
+interface HeaderObject extends BaseParameterObject {
+  $ref?: string;
+}
+interface ExamplesObject {
+  [name: string]: ExampleObject | ReferenceObject;
+}
+interface ReferenceObject {
+  $ref: string;
+  summary?: string;
+  description?: string;
+}
+type SchemaObjectType = 'integer' | 'number' | 'string' | 'boolean' | 'object' | 'null' | 'array';
+interface SchemaObject extends ISpecificationExtension {
+  $ref?: string;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XmlObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  examples?: any[];
+  deprecated?: boolean;
+  type?: SchemaObjectType | SchemaObjectType[];
+  format?: 'int32' | 'int64' | 'float' | 'double' | 'byte' | 'binary' | 'date' | 'date-time' | 'password' | string;
+  allOf?: (SchemaObject | ReferenceObject)[];
+  oneOf?: (SchemaObject | ReferenceObject)[];
+  anyOf?: (SchemaObject | ReferenceObject)[];
+  not?: SchemaObject | ReferenceObject;
+  items?: SchemaObject | ReferenceObject;
+  properties?: {
+    [propertyName: string]: SchemaObject | ReferenceObject;
+  };
+  additionalProperties?: SchemaObject | ReferenceObject | boolean;
+  propertyNames?: SchemaObject | ReferenceObject;
+  description?: string;
+  default?: any;
+  title?: string;
+  multipleOf?: number;
+  maximum?: number;
+  const?: any;
+  exclusiveMaximum?: number;
+  minimum?: number;
+  exclusiveMinimum?: number;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  enum?: any[];
+  prefixItems?: (SchemaObject | ReferenceObject)[];
+  contentMediaType?: string;
+  contentEncoding?: string;
+}
+interface DiscriminatorObject {
+  propertyName: string;
+  mapping?: {
+    [key: string]: string;
+  };
+}
+interface XmlObject extends ISpecificationExtension {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+}
+type ZodOpenApiOverrideMetaContext = OverrideSchemaParameters;
+type ZodOpenApiOverrideMeta = (ctx: ZodOpenApiOverrideMetaContext) => void;
+interface ZodOpenApiBaseMetadata {
+  /**
+   * Used to set metadata for a parameter
+   */
+  param?: Partial<ParameterObject> & {
+    /**
+     * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
+     */
+    id?: string;
+  };
+  /**
+   * Used to set metadata for a response header
+   */
+  header?: Partial<HeaderObject> & {
+    /**
+     * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
+     */
+    id?: string;
+  };
+  /**
+   * Use to override the rendered schema
+   */
+  override?: SchemaObject | ZodOpenApiOverrideMeta;
+  /**
+   * For use only if this Zod Schema is manually registered in the `components` section
+   * and is not used anywhere else in the document.
+   * Defaults to `output` if not specified.
+   */
+  unusedIO?: 'input' | 'output';
+  /**
+   * An alternate id to use for this schema in the event a registered schema is used in both a request and response schema.
+   * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
+   */
+  outputId?: string;
+}
+interface ZodOpenApiMetadata extends ZodOpenApiBaseMetadata, JSONSchemaMeta {
+  examples?: unknown[];
+  /**
+   * @deprecated - Use `examples` instead.
+   * Use of `example` is discouraged, and later versions of OpenAPI specification may remove it.
+   */
+  example?: unknown;
+}
+declare module 'zod/v4' {
+  interface GlobalMeta extends ZodOpenApiMetadata {}
+}
+
+/**
+ * Trait namespace — allows multiple trait-contributing providers to register
+ * under `traits:<namespace>` and merge into the unified traits bag.
+ *
+ * SDK built-ins: `'traits:trial'`, `'traits:usage'`.
+ * Customers can register any namespace (e.g. `'traits:permissions'`,
+ * `'traits:feature_flags'`).
+ */
+type TraitsNamespace = `traits:${string}`;
+/**
+ * Domain names recognized by the SDK provider registry.
+ * Each domain maps to a specific decision-engine input primitive.
+ *
+ * The `traits` domain and any `traits:<namespace>` domain are merged
+ * into a single `traits` slot in `ResolvedProviderContext`.
+ */
+type DomainProviderName = 'plan' | 'entitlements' | 'segments' | 'experiments' | 'content' | 'rules' | 'traits' | 'theme' | 'events' | 'cta' | TraitsNamespace;
+/**
+ * Base interface all domain providers implement.
+ *
+ * A domain provider supplies a named slice of the decision-engine's input:
+ * current plan, entitlement state, user segments, marketing content, rules,
+ * or custom traits.
+ */
+interface DomainProvider<D extends DomainProviderName = DomainProviderName, T = unknown> {
+    /** Provider domain name — used as the registry key. */
+    readonly domain: D;
+    /**
+     * Resolve the current value. Called before placement decisions.
+     * May be async (e.g. reading from a database or API).
+     */
+    resolve(): T | Promise<T>;
+    /**
+     * Optional: subscribe to changes (enables push-based invalidation).
+     * Returns an unsubscribe function.
+     */
+    subscribe?(listener: (next: T) => void): () => void;
+    /** Cache TTL in ms. 0 = re-resolve every call (default). */
+    cacheTtlMs?: number;
+}
+/**
+ * The user's experiment assignments, keyed by **experiment handle** with the
+ * assigned **variant handle** as the value (plan 183).
+ *
+ * Handles on both sides, deliberately: a handle is the canonical, version-stable
+ * identifier, which is what a `Segment.experiment_id` match and an analytics
+ * grouping must key on. The version id — which *definition* of the experiment
+ * was live — travels separately in telemetry, never as the match key.
+ *
+ * A map because a user can be enrolled in several experiments at once. Absent or
+ * empty means enrolled in nothing, which is distinct from "assigned to control".
+ */
+interface ExperimentProviderState {
+    /** `{ [experimentHandle]: variantHandle }`. */
+    assignments: Record<string, string>;
+}
+/**
+ * Supplies experiment enrollment and variant assignment.
+ *
+ * The binding declares whether RevTurbine manages the desired allocation or an
+ * external provider is authoritative. Both modes satisfy this one interface,
+ * so segment matching, decisions and telemetry never need to know which
+ * produced a value.
+ */
+interface ExperimentAssignmentProvider extends DomainProvider<'experiments', ExperimentProviderState> {
+    readonly domain: 'experiments';
+}
+
+/**
+ * GrowthBook-backed experiment assignment provider.
+ *
+ * The GrowthBook client is injected by the customer. This adapter therefore
+ * evaluates the customer's real GrowthBook instance without bundling its SDK,
+ * fetching credentials, or accepting executable customer code.
+ */
+
+/** One RevTurbine experiment handle mapped to its GrowthBook feature key. */
+interface GrowthBookExperimentBinding {
+    /** Stable RevTurbine experiment handle emitted in normalized assignments. */
+    experimentHandle: string;
+    /** GrowthBook feature key whose evaluated string value is the variant handle. */
+    featureKey: string;
+    /** Optional allowlist that rejects unexpected GrowthBook variant values. */
+    allowedVariants?: readonly string[];
+}
+/** Options for the separately bundled GrowthBook assignment adapter. */
+interface GrowthBookExperimentAssignmentOptions {
+    /** An initialized customer-owned GrowthBook client. */
+    client: Pick<GrowthBook<Record<string, string>>, 'evalFeature'>;
+    /** Explicit experiment-to-feature mappings; no naming convention is assumed. */
+    bindings: readonly GrowthBookExperimentBinding[];
+}
+/** Machine-readable reasons a GrowthBook assignment cannot be normalized. */
+type GrowthBookAssignmentErrorReason = 'duplicate_experiment_handle' | 'unknown_feature' | 'invalid_variant' | 'unexpected_variant';
+/** Raised when GrowthBook cannot produce a valid normalized assignment. */
+declare class GrowthBookAssignmentError extends Error {
+    /** Stable reason suitable for logs and error handling. */
+    readonly reason: GrowthBookAssignmentErrorReason;
+    /** RevTurbine experiment whose assignment failed. */
+    readonly experimentHandle: string;
+    /** GrowthBook feature evaluated for the assignment. */
+    readonly featureKey: string;
+    /** Construct a named GrowthBook normalization failure. */
+    constructor(reason: GrowthBookAssignmentErrorReason, binding: GrowthBookExperimentBinding, detail: string);
+}
+/**
+ * Create an assignment provider backed by an initialized GrowthBook client.
+ *
+ * Each GrowthBook feature must evaluate to a non-empty string variant handle.
+ * Unknown features and invalid values fail explicitly instead of being
+ * converted to an empty assignment or fabricated fallback.
+ */
+declare function createGrowthBookExperimentAssignmentProvider(options: GrowthBookExperimentAssignmentOptions): ExperimentAssignmentProvider;
+
+export { GrowthBookAssignmentError, createGrowthBookExperimentAssignmentProvider };
+export type { GrowthBookAssignmentErrorReason, GrowthBookExperimentAssignmentOptions, GrowthBookExperimentBinding };

package/dist/growthbook.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var d=(r,n,e)=>n in r?s(r,n,{enumerable:true,configurable:true,writable:true,value:e}):r[n]=e;var i=(r,n,e)=>d(r,typeof n!="symbol"?n+"":n,e);var o=class extends Error{constructor(e,t,a){super(`GrowthBook assignment for experiment "${t.experimentHandle}" (feature "${t.featureKey}") failed: ${a}`);i(this,"reason");i(this,"experimentHandle");i(this,"featureKey");this.name="GrowthBookAssignmentError",this.reason=e,this.experimentHandle=t.experimentHandle,this.featureKey=t.featureKey;}};function m(r){let n=new Set;for(let e of r){if(n.has(e.experimentHandle))throw new o("duplicate_experiment_handle",e,"the experiment handle is mapped more than once");n.add(e.experimentHandle);}}function p(r){return m(r.bindings),{domain:"experiments",resolve(){let n={};for(let e of r.bindings){let t=r.client.evalFeature(e.featureKey);if(t.source==="unknownFeature")throw new o("unknown_feature",e,"GrowthBook reported an unknown feature");if(typeof t.value!="string"||t.value.length===0)throw new o("invalid_variant",e,"the evaluated value must be a non-empty string variant handle");if(e.allowedVariants&&!e.allowedVariants.includes(t.value))throw new o("unexpected_variant",e,`variant "${t.value}" is outside the configured allowlist`);n[e.experimentHandle]=t.value;}return {assignments:n}}}}export{o as GrowthBookAssignmentError,p as createGrowthBookExperimentAssignmentProvider};//# sourceMappingURL=growthbook.js.map
+//# sourceMappingURL=growthbook.js.map

package/dist/growthbook.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../providers/growthbook-experiment-provider.ts"],"names":["GrowthBookAssignmentError","reason","binding","detail","__publicField","validateBindings","bindings","handles","createGrowthBookExperimentAssignmentProvider","options","assignments","result"],"mappings":"AAuCO,IAAA,CAAA,CAAA,MAAA,CAAA,cAAA,CAAA,IAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,GAAA,CAAA,IAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,UAAA,CAAA,IAAA,CAAA,YAAA,CAAA,IAAA,CAAA,QAAA,CAAA,IAAA,CAAA,KAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,IAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,GAAA,CAAA,CAAA,CAAA,CAAA,OAAA,CAAA,EAAA,QAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,IAAMA,EAAN,cAAwC,KAAM,CASnD,WAAA,CACEC,EACAC,CAAAA,CACAC,CAAAA,CACA,CACA,KAAA,CACE,yCAAyCD,CAAAA,CAAQ,gBAAgB,eAClDA,CAAAA,CAAQ,UAAU,cAAcC,CAAM,CAAA,CACvD,CAAA,CAfFC,CAAAA,CAAA,KAAS,QAAA,CAAA,CAETA,CAAAA,CAAA,KAAS,kBAAA,CAAA,CAETA,CAAAA,CAAA,KAAS,YAAA,CAAA,CAYP,IAAA,CAAK,IAAA,CAAO,2BAAA,CACZ,KAAK,MAAA,CAASH,CAAAA,CACd,KAAK,gBAAA,CAAmBC,CAAAA,CAAQ,iBAChC,IAAA,CAAK,UAAA,CAAaA,CAAAA,CAAQ,WAC5B,CACF,EAEA,SAASG,CAAAA,CAAiBC,CAAAA,CAAwD,CAChF,IAAMC,CAAAA,CAAU,IAAI,GAAA,CACpB,QAAWL,CAAAA,IAAWI,CAAAA,CAAU,CAC9B,GAAIC,CAAAA,CAAQ,IAAIL,CAAAA,CAAQ,gBAAgB,CAAA,CACtC,MAAM,IAAIF,CAAAA,CACR,6BAAA,CACAE,EACA,gDACF,CAAA,CAEFK,EAAQ,GAAA,CAAIL,CAAAA,CAAQ,gBAAgB,EACtC,CACF,CASO,SAASM,EACdC,CAAAA,CAC8B,CAC9B,OAAAJ,CAAAA,CAAiBI,CAAAA,CAAQ,QAAQ,CAAA,CAE1B,CACL,MAAA,CAAQ,aAAA,CACR,OAAA,EAAmC,CACjC,IAAMC,CAAAA,CAAsC,EAAC,CAE7C,IAAA,IAAWR,KAAWO,CAAAA,CAAQ,QAAA,CAAU,CACtC,IAAME,CAAAA,CAASF,EAAQ,MAAA,CAAO,WAAA,CAAYP,CAAAA,CAAQ,UAAU,EAC5D,GAAIS,CAAAA,CAAO,SAAW,gBAAA,CACpB,MAAM,IAAIX,CAAAA,CACR,iBAAA,CACAE,CAAAA,CACA,wCACF,EAGF,GAAI,OAAOS,EAAO,KAAA,EAAU,QAAA,EAAYA,EAAO,KAAA,CAAM,MAAA,GAAW,CAAA,CAC9D,MAAM,IAAIX,CAAAA,CACR,iBAAA,CACAE,CAAAA,CACA,+DACF,EAGF,GAAIA,CAAAA,CAAQ,eAAA,EAAmB,CAACA,EAAQ,eAAA,CAAgB,QAAA,CAASS,EAAO,KAAK,CAAA,CAC3E,MAAM,IAAIX,CAAAA,CACR,oBAAA,CACAE,CAAAA,CACA,YAAYS,CAAAA,CAAO,KAAK,uCAC1B,CAAA,CAGFD,CAAAA,CAAYR,EAAQ,gBAAgB,CAAA,CAAIS,CAAAA,CAAO,MACjD,CAEA,OAAO,CAAE,YAAAD,CAAY,CACvB,CACF,CACF","file":"growthbook.js","sourcesContent":["/**\n * GrowthBook-backed experiment assignment provider.\n *\n * The GrowthBook client is injected by the customer. This adapter therefore\n * evaluates the customer's real GrowthBook instance without bundling its SDK,\n * fetching credentials, or accepting executable customer code.\n */\nimport type { GrowthBook } from '@growthbook/growthbook';\nimport type {\n  ExperimentAssignmentProvider,\n  ExperimentProviderState,\n} from '@revt-eng/core';\n\n/** One RevTurbine experiment handle mapped to its GrowthBook feature key. */\nexport interface GrowthBookExperimentBinding {\n  /** Stable RevTurbine experiment handle emitted in normalized assignments. */\n  experimentHandle: string;\n  /** GrowthBook feature key whose evaluated string value is the variant handle. */\n  featureKey: string;\n  /** Optional allowlist that rejects unexpected GrowthBook variant values. */\n  allowedVariants?: readonly string[];\n}\n\n/** Options for the separately bundled GrowthBook assignment adapter. */\nexport interface GrowthBookExperimentAssignmentOptions {\n  /** An initialized customer-owned GrowthBook client. */\n  client: Pick<GrowthBook<Record<string, string>>, 'evalFeature'>;\n  /** Explicit experiment-to-feature mappings; no naming convention is assumed. */\n  bindings: readonly GrowthBookExperimentBinding[];\n}\n\n/** Machine-readable reasons a GrowthBook assignment cannot be normalized. */\nexport type GrowthBookAssignmentErrorReason =\n  | 'duplicate_experiment_handle'\n  | 'unknown_feature'\n  | 'invalid_variant'\n  | 'unexpected_variant';\n\n/** Raised when GrowthBook cannot produce a valid normalized assignment. */\nexport class GrowthBookAssignmentError extends Error {\n  /** Stable reason suitable for logs and error handling. */\n  readonly reason: GrowthBookAssignmentErrorReason;\n  /** RevTurbine experiment whose assignment failed. */\n  readonly experimentHandle: string;\n  /** GrowthBook feature evaluated for the assignment. */\n  readonly featureKey: string;\n\n  /** Construct a named GrowthBook normalization failure. */\n  constructor(\n    reason: GrowthBookAssignmentErrorReason,\n    binding: GrowthBookExperimentBinding,\n    detail: string,\n  ) {\n    super(\n      `GrowthBook assignment for experiment \"${binding.experimentHandle}\" `\n      + `(feature \"${binding.featureKey}\") failed: ${detail}`,\n    );\n    this.name = 'GrowthBookAssignmentError';\n    this.reason = reason;\n    this.experimentHandle = binding.experimentHandle;\n    this.featureKey = binding.featureKey;\n  }\n}\n\nfunction validateBindings(bindings: readonly GrowthBookExperimentBinding[]): void {\n  const handles = new Set<string>();\n  for (const binding of bindings) {\n    if (handles.has(binding.experimentHandle)) {\n      throw new GrowthBookAssignmentError(\n        'duplicate_experiment_handle',\n        binding,\n        'the experiment handle is mapped more than once',\n      );\n    }\n    handles.add(binding.experimentHandle);\n  }\n}\n\n/**\n * Create an assignment provider backed by an initialized GrowthBook client.\n *\n * Each GrowthBook feature must evaluate to a non-empty string variant handle.\n * Unknown features and invalid values fail explicitly instead of being\n * converted to an empty assignment or fabricated fallback.\n */\nexport function createGrowthBookExperimentAssignmentProvider(\n  options: GrowthBookExperimentAssignmentOptions,\n): ExperimentAssignmentProvider {\n  validateBindings(options.bindings);\n\n  return {\n    domain: 'experiments',\n    resolve(): ExperimentProviderState {\n      const assignments: Record<string, string> = {};\n\n      for (const binding of options.bindings) {\n        const result = options.client.evalFeature(binding.featureKey);\n        if (result.source === 'unknownFeature') {\n          throw new GrowthBookAssignmentError(\n            'unknown_feature',\n            binding,\n            'GrowthBook reported an unknown feature',\n          );\n        }\n\n        if (typeof result.value !== 'string' || result.value.length === 0) {\n          throw new GrowthBookAssignmentError(\n            'invalid_variant',\n            binding,\n            'the evaluated value must be a non-empty string variant handle',\n          );\n        }\n\n        if (binding.allowedVariants && !binding.allowedVariants.includes(result.value)) {\n          throw new GrowthBookAssignmentError(\n            'unexpected_variant',\n            binding,\n            `variant \"${result.value}\" is outside the configured allowlist`,\n          );\n        }\n\n        assignments[binding.experimentHandle] = result.value;\n      }\n\n      return { assignments };\n    },\n  };\n}\n"]}