@oxyhq/core 2.4.0 → 3.0.0

package/src/mixins/index.ts

@@ -17,7 +17,7 @@ import { OxyServicesLanguageMixin } from './OxyServices.language';
 import { OxyServicesPaymentMixin } from './OxyServices.payment';
 import { OxyServicesKarmaMixin } from './OxyServices.karma';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
-import { OxyServicesDeveloperMixin } from './OxyServices.developer';
+import { OxyServicesApplicationsMixin } from './OxyServices.applications';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -50,7 +50,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>>
@@ -114,7 +114,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesPaymentMixin,
     OxyServicesKarmaMixin,
     OxyServicesAssetsMixin,
-    OxyServicesDeveloperMixin,
+    OxyServicesApplicationsMixin,
     OxyServicesLocationMixin,
     OxyServicesAnalyticsMixin,
     OxyServicesDevicesMixin,

package/src/utils/__tests__/coldBoot.test.ts

@@ -223,4 +223,154 @@ describe('runColdBoot', () => {
       session: { userId: 'u-ok' },
     });
   });
+
+  describe('overall deadline (defense-in-depth)', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+    afterEach(() => {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    });
+
+    /**
+     * Reproduces the production hang: a step whose `run()` promise NEVER
+     * settles (the FedCM-silent `navigator.credentials.get` that ignored its
+     * abort signal). WITHOUT a deadline the whole `runColdBoot` promise hangs
+     * forever and the terminal step never runs.
+     */
+    it('hangs forever when a step never settles and no deadline is set', async () => {
+      const terminalRan = jest.fn();
+      let settled = false;
+
+      const outcomePromise = runColdBoot<TestSession>({
+        steps: [
+          {
+            id: 'never-settles',
+            // Never resolves or rejects — models the hung FedCM credential get.
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'terminal',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              terminalRan();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      }).then((o) => {
+        settled = true;
+        return o;
+      });
+
+      // Advance well past any reasonable budget; nothing can unblock it.
+      await jest.advanceTimersByTimeAsync(120000);
+
+      expect(settled).toBe(false);
+      expect(terminalRan).not.toHaveBeenCalled();
+
+      // Avoid a dangling unhandled promise in the test runner.
+      void outcomePromise;
+    });
+
+    /**
+     * With `overallDeadlineMs` set, the non-settling step is abandoned at the
+     * deadline, the runner CONTINUES to the terminal step (so the cross-domain
+     * `/sso` bounce equivalent still fires), and the whole boot settles to
+     * `unauthenticated` within the bounded budget.
+     */
+    it('abandons a non-settling step at the deadline and still runs the terminal step', async () => {
+      const terminalRan = jest.fn();
+      const onStepDeadline = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 5000,
+        onStepDeadline,
+        steps: [
+          {
+            id: 'never-settles',
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'terminal',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              terminalRan();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(5000);
+      const outcome = await outcomePromise;
+
+      expect(onStepDeadline).toHaveBeenCalledWith('never-settles');
+      expect(terminalRan).toHaveBeenCalledTimes(1);
+      expect(outcome).toEqual({ kind: 'unauthenticated' });
+    });
+
+    /**
+     * The terminal step's synchronous side effect (the real `sso-bounce`
+     * navigates BEFORE its first await) must still execute when the deadline
+     * trips on an earlier step — the cross-domain fallback is preserved.
+     */
+    it('lets the terminal step fire its synchronous side effect after the deadline trips', async () => {
+      const bounced = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 3000,
+        steps: [
+          {
+            id: 'never-settles',
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'sso-bounce',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              // Synchronous navigation side effect, exactly like the real bounce.
+              bounced();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(3000);
+      await outcomePromise;
+
+      expect(bounced).toHaveBeenCalledTimes(1);
+    });
+
+    /**
+     * A healthy step that settles BEFORE the deadline still wins and
+     * short-circuits — the deadline never alters the happy path.
+     */
+    it('a step that settles before the deadline wins and short-circuits', async () => {
+      const laterRan = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 10000,
+        steps: [
+          {
+            id: 'fast-winner',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              await Promise.resolve();
+              return { kind: 'session', session: { userId: 'u-fast' } };
+            },
+          },
+          sessionStep('later', 'u-later', laterRan),
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(0);
+      const outcome = await outcomePromise;
+
+      expect(outcome).toEqual({
+        kind: 'session',
+        via: 'fast-winner',
+        session: { userId: 'u-fast' },
+      });
+      expect(laterRan).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/utils/coldBoot.ts

@@ -73,6 +73,16 @@ export type ColdBootOutcome<S> =
   | { readonly kind: 'session'; readonly via: string; readonly session: S }
   | { readonly kind: 'unauthenticated' };
 
+/**
+ * The unique sentinel a step's `run()` resolves to (via the internal race)
+ * when the overall cold-boot deadline expires before that step settled. It is
+ * NOT a {@link ColdBootStepResult} — the runner detects it by identity and
+ * treats it as "this step did not settle in time; move on".
+ *
+ * @internal
+ */
+const DEADLINE_EXPIRED: unique symbol = Symbol('coldBoot.deadlineExpired');
+
 /**
  * Options for {@link runColdBoot}.
  */
@@ -85,6 +95,32 @@ export interface RunColdBootOptions<S> {
    * the runner does not guard against an observer that itself throws.
    */
   readonly onStepError?: (id: string, error: unknown) => void;
+  /**
+   * Optional HARD overall deadline (ms) for the entire ordered step loop —
+   * defense-in-depth so a single non-settling step can NEVER hang the whole
+   * cold boot forever.
+   *
+   * Each step's `run()` is raced against the SHARED remaining time. If a step
+   * fails to settle before the deadline, the runner abandons the await for that
+   * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
+   * each now racing against an already-expired deadline. This is deliberate:
+   * the runner keeps iterating so the TERMINAL step (e.g. the `/sso` bounce,
+   * whose `run()` performs its side effect synchronously before its first
+   * `await`) still gets to fire. A step that has nothing to contribute after
+   * the deadline simply doesn't settle and is skipped in turn.
+   *
+   * Per-step timeouts inside `run()` remain the first line of defense and
+   * should keep every step well under this budget on a healthy load; this only
+   * trips when one of them regresses (the production FedCM-silent hang). When
+   * omitted there is NO overall deadline (unchanged legacy behaviour).
+   */
+  readonly overallDeadlineMs?: number;
+  /**
+   * Optional observer invoked once per step that was abandoned because the
+   * overall deadline expired before it settled. Receives the step `id`. Must
+   * not throw.
+   */
+  readonly onStepDeadline?: (id: string) => void;
 }
 
 /**
@@ -105,32 +141,75 @@ export interface RunColdBootOptions<S> {
 export async function runColdBoot<S>(
   options: RunColdBootOptions<S>
 ): Promise<ColdBootOutcome<S>> {
-  const { steps, onStepError } = options;
+  const { steps, onStepError, overallDeadlineMs, onStepDeadline } = options;
 
-  for (const step of steps) {
-    if (step.enabled) {
-      let isEnabled: boolean;
+  // Arm the optional overall deadline. The budget is SHARED across the whole
+  // loop (not reset per step): a single timer resolves a reusable
+  // `DEADLINE_EXPIRED` sentinel that every per-step race can observe. Once it
+  // fires, later steps race against an already-resolved promise and so never
+  // block, yet the loop keeps iterating so the terminal step still fires.
+  const deadlineMs =
+    typeof overallDeadlineMs === 'number' &&
+    Number.isFinite(overallDeadlineMs) &&
+    overallDeadlineMs > 0
+      ? overallDeadlineMs
+      : null;
+
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let deadlinePromise: Promise<typeof DEADLINE_EXPIRED> | undefined;
+  if (deadlineMs !== null) {
+    deadlinePromise = new Promise<typeof DEADLINE_EXPIRED>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve(DEADLINE_EXPIRED), deadlineMs);
+    });
+  }
+
+  try {
+    for (const step of steps) {
+      if (step.enabled) {
+        let isEnabled: boolean;
+        try {
+          isEnabled = step.enabled();
+        } catch (error) {
+          onStepError?.(step.id, error);
+          continue;
+        }
+        if (!isEnabled) continue;
+      }
+
+      let result: ColdBootStepResult<S> | typeof DEADLINE_EXPIRED;
       try {
-        isEnabled = step.enabled();
+        // Without a deadline: legacy behaviour — await the step directly.
+        // With a deadline: race the step against the shared deadline. The
+        // step's `run()` still STARTS synchronously up to its first `await`
+        // (so a terminal step's synchronous navigation side effect always
+        // executes), but a non-settling step can no longer block the loop —
+        // the race resolves with the sentinel and we move on.
+        result = deadlinePromise
+          ? await Promise.race([step.run(), deadlinePromise])
+          : await step.run();
       } catch (error) {
         onStepError?.(step.id, error);
         continue;
       }
-      if (!isEnabled) continue;
-    }
 
-    let result: ColdBootStepResult<S>;
-    try {
-      result = await step.run();
-    } catch (error) {
-      onStepError?.(step.id, error);
-      continue;
+      if (result === DEADLINE_EXPIRED) {
+        // The deadline tripped before this step settled. Abandon the await and
+        // continue: subsequent steps race against the already-resolved deadline
+        // (so they cannot block), which lets a terminal side-effect step still
+        // run while guaranteeing the loop terminates promptly.
+        onStepDeadline?.(step.id);
+        continue;
+      }
+
+      if (result.kind === 'session') {
+        return { kind: 'session', via: step.id, session: result.session };
+      }
     }
 
-    if (result.kind === 'session') {
-      return { kind: 'session', via: step.id, session: result.session };
+    return { kind: 'unauthenticated' };
+  } finally {
+    if (deadlineTimer !== undefined) {
+      clearTimeout(deadlineTimer);
     }
   }
-
-  return { kind: 'unauthenticated' };
 }

package/src/mixins/OxyServices.developer.ts

@@ -1,114 +0,0 @@
-/**
- * Developer API Methods Mixin
- * 
- * Provides methods for managing developer applications and API keys
- */
-import type { OxyServicesBase } from '../OxyServices.base';
-import { CACHE_TIMES } from './mixinHelpers';
-
-export function OxyServicesDeveloperMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Get developer apps for the current user
-     * @returns Array of developer apps
-     */
-    async getDeveloperApps(): Promise<any[]> {
-      try {
-        const res = await this.makeRequest<{ apps?: any[] }>('GET', '/developer/apps', undefined, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.MEDIUM,
-        });
-        return res.apps || [];
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Create a new developer app
-     * @param data - Developer app configuration
-     * @returns Created developer app
-     */
-    async createDeveloperApp(data: {
-      name: string;
-      description?: string;
-      webhookUrl: string;
-      devWebhookUrl?: string;
-      scopes?: string[];
-    }): Promise<any> {
-      try {
-        const res = await this.makeRequest<{ app: any }>('POST', '/developer/apps', data, { cache: false });
-        return res.app;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Get a specific developer app
-     */
-    async getDeveloperApp(appId: string): Promise<any> {
-      try {
-      const res = await this.makeRequest<{ app: any }>('GET', `/developer/apps/${appId}`, undefined, {
-        cache: true,
-        cacheTTL: CACHE_TIMES.LONG,
-      });
-        return res.app;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Update a developer app
-     * @param appId - The developer app ID
-     * @param data - Updated app configuration
-     * @returns Updated developer app
-     */
-    async updateDeveloperApp(appId: string, data: {
-      name?: string;
-      description?: string;
-      webhookUrl?: string;
-      devWebhookUrl?: string;
-      scopes?: string[];
-    }): Promise<any> {
-      try {
-        const res = await this.makeRequest<{ app: any }>('PATCH', `/developer/apps/${appId}`, data, { cache: false });
-        return res.app;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Regenerate API secret for a developer app
-     * @param appId - The developer app ID
-     * @returns App with new secret
-     */
-    async regenerateDeveloperAppSecret(appId: string): Promise<any> {
-      try {
-        return await this.makeRequest('POST', `/developer/apps/${appId}/regenerate-secret`, undefined, { cache: false });
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Delete a developer app
-     * @param appId - The developer app ID
-     * @returns Deletion result
-     */
-    async deleteDeveloperApp(appId: string): Promise<any> {
-      try {
-        return await this.makeRequest('DELETE', `/developer/apps/${appId}`, undefined, { cache: false });
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-  };
-}
-