swetrix 3.7.1 → 4.0.0

package/dist/esnext/index.d.ts

@@ -1,4 +1,4 @@
-import { Lib, LibOptions, TrackEventOptions, PageViewsOptions, ErrorOptions, PageActions, ErrorActions, IErrorEventPayload, IPageViewPayload } from './Lib.js';
+import { Lib, LibOptions, TrackEventOptions, PageViewsOptions, ErrorOptions, PageActions, ErrorActions, IErrorEventPayload, IPageViewPayload, FeatureFlagsOptions, ExperimentOptions } from './Lib.js';
 export declare let LIB_INSTANCE: Lib | null;
 /**
  * Initialise the tracking library instance (other methods won't work if the library is not initialised).
@@ -54,4 +54,148 @@ export interface IPageviewOptions {
     unique?: boolean;
 }
 export declare function pageview(options: IPageviewOptions): void;
-export { LibOptions, TrackEventOptions, PageViewsOptions, ErrorOptions, PageActions, ErrorActions, IErrorEventPayload, IPageViewPayload, };
+/**
+ * Fetches all feature flags for the project.
+ * Results are cached for 5 minutes by default.
+ *
+ * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
+ * @returns A promise that resolves to a record of flag keys to boolean values.
+ *
+ * @example
+ * ```typescript
+ * const flags = await getFeatureFlags({
+ *   visitorId: 'user-123',
+ *   attributes: { cc: 'US', dv: 'desktop' }
+ * })
+ *
+ * if (flags['new-checkout']) {
+ *   // Show new checkout flow
+ * }
+ * ```
+ */
+export declare function getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>>;
+/**
+ * Gets the value of a single feature flag.
+ *
+ * @param key - The feature flag key.
+ * @param options - Options for evaluating the feature flag (visitorId, attributes).
+ * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @returns A promise that resolves to the boolean value of the flag.
+ *
+ * @example
+ * ```typescript
+ * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ *
+ * if (isEnabled) {
+ *   // Enable dark mode
+ * }
+ * ```
+ */
+export declare function getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue?: boolean): Promise<boolean>;
+/**
+ * Clears the cached feature flags, forcing a fresh fetch on the next call.
+ * Useful when you know the user's context has changed significantly.
+ */
+export declare function clearFeatureFlagsCache(): void;
+/**
+ * Fetches all A/B test experiments for the project.
+ * Results are cached for 5 minutes by default (shared cache with feature flags).
+ *
+ * @param options - Options for evaluating experiments.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+ * @returns A promise that resolves to a record of experiment IDs to variant keys.
+ *
+ * @example
+ * ```typescript
+ * const experiments = await getExperiments()
+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+ *
+ * // Use the assigned variant
+ * const checkoutVariant = experiments['checkout-experiment-id']
+ * if (checkoutVariant === 'new-checkout') {
+ *   showNewCheckout()
+ * } else {
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export declare function getExperiments(options?: ExperimentOptions, forceRefresh?: boolean): Promise<Record<string, string>>;
+/**
+ * Gets the variant key for a specific A/B test experiment.
+ *
+ * @param experimentId - The experiment ID.
+ * @param options - Options for evaluating the experiment.
+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+ *
+ * @example
+ * ```typescript
+ * const variant = await getExperiment('checkout-redesign-experiment-id')
+ *
+ * if (variant === 'new-checkout') {
+ *   // Show new checkout flow
+ *   showNewCheckout()
+ * } else if (variant === 'control') {
+ *   // Show original checkout (control group)
+ *   showOriginalCheckout()
+ * } else {
+ *   // Experiment not running or user not included
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export declare function getExperiment(experimentId: string, options?: ExperimentOptions, defaultVariant?: string | null): Promise<string | null>;
+/**
+ * Clears the cached experiments, forcing a fresh fetch on the next call.
+ * This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.
+ */
+export declare function clearExperimentsCache(): void;
+/**
+ * Gets the anonymous profile ID for the current visitor.
+ * If profileId was set via init options, returns that.
+ * Otherwise, requests server to generate one from IP/UA hash.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the profile ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const profileId = await getProfileId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: profileId,
+ *     swetrix_session_id: await getSessionId()
+ *   }
+ * })
+ * ```
+ */
+export declare function getProfileId(): Promise<string | null>;
+/**
+ * Gets the current session ID for the visitor.
+ * Session IDs are generated server-side based on IP and user agent.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the session ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const sessionId = await getSessionId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: await getProfileId(),
+ *     swetrix_session_id: sessionId
+ *   }
+ * })
+ * ```
+ */
+export declare function getSessionId(): Promise<string | null>;
+export { LibOptions, TrackEventOptions, PageViewsOptions, ErrorOptions, PageActions, ErrorActions, IErrorEventPayload, IPageViewPayload, FeatureFlagsOptions, ExperimentOptions, };

package/dist/esnext/index.js

@@ -93,4 +93,180 @@ export function pageview(options) {
         return;
     LIB_INSTANCE.submitPageView(options.payload, Boolean(options.unique), {});
 }
+/**
+ * Fetches all feature flags for the project.
+ * Results are cached for 5 minutes by default.
+ *
+ * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
+ * @returns A promise that resolves to a record of flag keys to boolean values.
+ *
+ * @example
+ * ```typescript
+ * const flags = await getFeatureFlags({
+ *   visitorId: 'user-123',
+ *   attributes: { cc: 'US', dv: 'desktop' }
+ * })
+ *
+ * if (flags['new-checkout']) {
+ *   // Show new checkout flow
+ * }
+ * ```
+ */
+export async function getFeatureFlags(options, forceRefresh) {
+    if (!LIB_INSTANCE)
+        return {};
+    return LIB_INSTANCE.getFeatureFlags(options, forceRefresh);
+}
+/**
+ * Gets the value of a single feature flag.
+ *
+ * @param key - The feature flag key.
+ * @param options - Options for evaluating the feature flag (visitorId, attributes).
+ * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @returns A promise that resolves to the boolean value of the flag.
+ *
+ * @example
+ * ```typescript
+ * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ *
+ * if (isEnabled) {
+ *   // Enable dark mode
+ * }
+ * ```
+ */
+export async function getFeatureFlag(key, options, defaultValue = false) {
+    if (!LIB_INSTANCE)
+        return defaultValue;
+    return LIB_INSTANCE.getFeatureFlag(key, options, defaultValue);
+}
+/**
+ * Clears the cached feature flags, forcing a fresh fetch on the next call.
+ * Useful when you know the user's context has changed significantly.
+ */
+export function clearFeatureFlagsCache() {
+    if (!LIB_INSTANCE)
+        return;
+    LIB_INSTANCE.clearFeatureFlagsCache();
+}
+/**
+ * Fetches all A/B test experiments for the project.
+ * Results are cached for 5 minutes by default (shared cache with feature flags).
+ *
+ * @param options - Options for evaluating experiments.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+ * @returns A promise that resolves to a record of experiment IDs to variant keys.
+ *
+ * @example
+ * ```typescript
+ * const experiments = await getExperiments()
+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+ *
+ * // Use the assigned variant
+ * const checkoutVariant = experiments['checkout-experiment-id']
+ * if (checkoutVariant === 'new-checkout') {
+ *   showNewCheckout()
+ * } else {
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiments(options, forceRefresh) {
+    if (!LIB_INSTANCE)
+        return {};
+    return LIB_INSTANCE.getExperiments(options, forceRefresh);
+}
+/**
+ * Gets the variant key for a specific A/B test experiment.
+ *
+ * @param experimentId - The experiment ID.
+ * @param options - Options for evaluating the experiment.
+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+ *
+ * @example
+ * ```typescript
+ * const variant = await getExperiment('checkout-redesign-experiment-id')
+ *
+ * if (variant === 'new-checkout') {
+ *   // Show new checkout flow
+ *   showNewCheckout()
+ * } else if (variant === 'control') {
+ *   // Show original checkout (control group)
+ *   showOriginalCheckout()
+ * } else {
+ *   // Experiment not running or user not included
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiment(experimentId, options, defaultVariant = null) {
+    if (!LIB_INSTANCE)
+        return defaultVariant;
+    return LIB_INSTANCE.getExperiment(experimentId, options, defaultVariant);
+}
+/**
+ * Clears the cached experiments, forcing a fresh fetch on the next call.
+ * This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.
+ */
+export function clearExperimentsCache() {
+    if (!LIB_INSTANCE)
+        return;
+    LIB_INSTANCE.clearExperimentsCache();
+}
+/**
+ * Gets the anonymous profile ID for the current visitor.
+ * If profileId was set via init options, returns that.
+ * Otherwise, requests server to generate one from IP/UA hash.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the profile ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const profileId = await getProfileId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: profileId,
+ *     swetrix_session_id: await getSessionId()
+ *   }
+ * })
+ * ```
+ */
+export async function getProfileId() {
+    if (!LIB_INSTANCE)
+        return null;
+    return LIB_INSTANCE.getProfileId();
+}
+/**
+ * Gets the current session ID for the visitor.
+ * Session IDs are generated server-side based on IP and user agent.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the session ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const sessionId = await getSessionId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: await getProfileId(),
+ *     swetrix_session_id: sessionId
+ *   }
+ * })
+ * ```
+ */
+export async function getSessionId() {
+    if (!LIB_INSTANCE)
+        return null;
+    return LIB_INSTANCE.getSessionId();
+}
 //# sourceMappingURL=index.js.map

package/dist/esnext/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EAOH,cAAc,GAGf,MAAM,UAAU,CAAA;AAEjB,MAAM,CAAC,IAAI,YAAY,GAAe,IAAI,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAC,GAAW,EAAE,OAAoB;IACpD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACtC,CAAC;IAED,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,KAAwB;IAClD,IAAI,CAAC,YAAY;QAAE,OAAM;IAEzB,MAAM,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,CAAC,cAAc,CAAC,CAAA;YACvB,OAAM;QACR,CAAC;QAED,8GAA8G;QAC9G,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;YAC1E,OAAO,CAAC,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAA;QAC/C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;gBACnC,aAAa;gBACb,OAAO,CAAC,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAA;YAC/C,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,OAAO,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAA2B;IACpD,IAAI,CAAC,YAAY;QAAE,OAAM;IAEzB,YAAY,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,KAAc,EAAE,MAAgB;IACxE,IAAI,CAAC,YAAY;QAAE,OAAM;IAEzB,YAAY,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;AAC1D,CAAC;AAOD,MAAM,UAAU,QAAQ,CAAC,OAAyB;IAChD,IAAI,CAAC,YAAY;QAAE,OAAM;IAEzB,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;AAC3E,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}