@tuturuuu/utils 0.8.0 → 0.9.0

package/src/api-proxy-guard.ts

@@ -31,10 +31,10 @@ function isEnvFlagEnabled(name: string, defaultOn = true): boolean {
 }
 
 /**
- * Whether trusted accounts/locations get scaled read limits (and trusted
+ * Whether trusted accounts/locations get scaled read limits (and verified
  * sessions get their own per-session bucket) at the edge. Default on; set
  * `API_PROXY_EDGE_TRUST_ENABLED=0` to disable trust uplift and fall back to
- * legacy per-IP read limiting without a deploy.
+ * legacy per-IP keying without a deploy.
  */
 function edgeTrustEnabled(): boolean {
   return isEnvFlagEnabled('API_PROXY_EDGE_TRUST_ENABLED');
@@ -187,18 +187,39 @@ const DEFAULT_ANONYMOUS_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   createConfig('day', '1 d', 600, 'API_PROXY_ANON_MUTATE_LIMIT_DAY'),
 ];
 
+const DEFAULT_AUTHENTICATED_READ_RATE_LIMITS: RateLimitConfig[] = [
+  createConfig('minute', '1 m', 600, 'API_PROXY_AUTH_READ_LIMIT_MINUTE'),
+  createConfig('hour', '1 h', 6000, 'API_PROXY_AUTH_READ_LIMIT_HOUR'),
+  createConfig('day', '1 d', 40_000, 'API_PROXY_AUTH_READ_LIMIT_DAY'),
+];
+
 const DEFAULT_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   { window: 'minute', limit: 60, duration: '1 m' },
   { window: 'hour', limit: 300, duration: '1 h' },
   { window: 'day', limit: 2000, duration: '1 d' },
 ];
 
+const USERS_ME_READ_RATE_LIMITS: RateLimitConfig[] = [
+  createConfig('minute', '1 m', 600, 'API_PROXY_USERS_ME_READ_LIMIT_MINUTE'),
+  createConfig('hour', '1 h', 6000, 'API_PROXY_USERS_ME_READ_LIMIT_HOUR'),
+  createConfig('day', '1 d', 40_000, 'API_PROXY_USERS_ME_READ_LIMIT_DAY'),
+];
+
 const USERS_ME_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   { window: 'minute', limit: 60, duration: '1 m' },
   { window: 'hour', limit: 200, duration: '1 h' },
   { window: 'day', limit: 1200, duration: '1 d' },
 ];
 
+const WORKSPACE_DASHBOARD_READ_RATE_LIMITS: RateLimitProfile = {
+  get: [
+    createConfig('minute', '1 m', 600, 'API_PROXY_WORKSPACE_READ_LIMIT_MINUTE'),
+    createConfig('hour', '1 h', 6000, 'API_PROXY_WORKSPACE_READ_LIMIT_HOUR'),
+    createConfig('day', '1 d', 40_000, 'API_PROXY_WORKSPACE_READ_LIMIT_DAY'),
+  ],
+  mutate: DEFAULT_MUTATE_RATE_LIMITS,
+};
+
 const AUTH_RATE_LIMITS: RateLimitProfile = {
   get: NO_READ_RATE_LIMITS,
   mutate: [
@@ -312,6 +333,25 @@ const USERS_DATABASE_READ_OVER_POST_RATE_LIMITS: RateLimitProfile = {
   ],
 };
 
+const USERS_ADMIN_READ_RATE_LIMITS: RateLimitProfile = {
+  get: [
+    createConfig(
+      'minute',
+      '1 m',
+      1200,
+      'API_PROXY_USERS_ADMIN_READ_LIMIT_MINUTE'
+    ),
+    createConfig(
+      'hour',
+      '1 h',
+      12_000,
+      'API_PROXY_USERS_ADMIN_READ_LIMIT_HOUR'
+    ),
+    createConfig('day', '1 d', 80_000, 'API_PROXY_USERS_ADMIN_READ_LIMIT_DAY'),
+  ],
+  mutate: DEFAULT_MUTATE_RATE_LIMITS,
+};
+
 const FINANCE_READ_RATE_LIMITS: RateLimitProfile = {
   get: [
     createConfig('minute', '1 m', 1200, 'API_PROXY_FINANCE_READ_LIMIT_MINUTE', [
@@ -362,6 +402,33 @@ function isUsersDatabaseReadOverPost(req: NextRequest) {
   );
 }
 
+function isUsersAdminRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  const pathname = req.nextUrl.pathname;
+
+  return (
+    /^\/api\/v1\/workspaces\/[^/]+\/users(?:\/(?:database|groups|feedbacks|attendance\/export|[^/]+\/(?:attendance|emails|referrals|linked-promotions|referral-discounts|user-groups)))?\/?$/u.test(
+      pathname
+    ) ||
+    /^\/api\/v1\/workspaces\/[^/]+\/user-groups\/[^/]+(?:\/(?:attendance|members(?:\/[^/]+(?:\/feedbacks)?)?|posts(?:\/[^/]+(?:\/status)?)?|linked-products|storage|indicators(?:\/.*)?))?\/?$/u.test(
+      pathname
+    )
+  );
+}
+
+function isWorkspaceDashboardRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  return /^\/api(?:\/v1)?\/workspaces\/[^/]+(?:\/|$)/u.test(
+    req.nextUrl.pathname
+  );
+}
+
 const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
   {
     key: 'cron',
@@ -441,6 +508,16 @@ const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
     matches: isFinanceInvoiceCreateSupportRead,
     rateLimits: FINANCE_READ_RATE_LIMITS,
   },
+  {
+    key: 'users-admin-read',
+    matches: isUsersAdminRead,
+    rateLimits: USERS_ADMIN_READ_RATE_LIMITS,
+  },
+  {
+    key: 'workspace-dashboard-read',
+    matches: isWorkspaceDashboardRead,
+    rateLimits: WORKSPACE_DASHBOARD_READ_RATE_LIMITS,
+  },
   {
     key: 'high-fanout',
     matches: (req) =>
@@ -467,7 +544,7 @@ const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
     key: 'users-me',
     matches: (req) => req.nextUrl.pathname.startsWith('/api/v1/users/me'),
     rateLimits: {
-      get: NO_READ_RATE_LIMITS,
+      get: USERS_ME_READ_RATE_LIMITS,
       mutate: USERS_ME_MUTATE_RATE_LIMITS,
     },
   },
@@ -813,9 +890,10 @@ function getCallerClass(req: NextRequest): CallerClass {
   // Intentionally always 'anonymous'. Auth headers/cookies are forgeable at the
   // edge (we can't verify signatures cheaply here), so presence alone must never
   // grant an elevated proxy budget — real per-user enforcement happens
-  // downstream. Higher read throughput for genuinely trusted accounts/locations
-  // is granted instead via the server-written trust cache (see resolveProxyIdentity
-  // + getCachedTrustMultiplier), which cannot be forged.
+  // downstream. Per-session proxy buckets and higher read throughput for
+  // genuinely trusted accounts/locations are granted instead via the
+  // server-written trust cache (see resolveProxyIdentity +
+  // getCachedTrustEntries), which cannot be forged.
   void req;
   return 'anonymous';
 }
@@ -1050,6 +1128,13 @@ function getEffectiveRateLimits(
   callerClass: CallerClass
 ): RateLimitProfile {
   if (callerClass === 'authenticated') {
+    if (routePolicy.key === 'default') {
+      return {
+        get: DEFAULT_AUTHENTICATED_READ_RATE_LIMITS,
+        mutate: DEFAULT_MUTATE_RATE_LIMITS,
+      };
+    }
+
     return routePolicy.rateLimits;
   }
 
@@ -1179,57 +1264,70 @@ export async function guardApiProxyRequest(
     const routePolicy = getRoutePolicy(req, routePolicies);
     const isRead = req.method === 'GET' || req.method === 'HEAD';
 
-    // Resolve trust for reads only. Account trust (session key) and location
+    // Resolve server-verified session keying for reads and mutations, but apply
+    // trust uplift to read limits only. Account trust (session key) and location
     // trust (cidr/ip keys) are distinguished so that:
-    //   * a genuinely trusted SESSION (cache entry keyed on the real cookie's
-    //     hash — unforgeable) gets its OWN per-session bucket, so trusted
+    //   * a server-verified SESSION (cache entry keyed on the real cookie's
+    //     hash — unforgeable) gets its OWN per-session bucket, so signed-in
     //     teammates behind one NAT no longer collide; and
     //   * a trusted LOCATION (office cidr/ip) uplifts the shared per-IP bucket
     //     for the whole team without any per-request credential.
     // Untrusted traffic keeps legacy per-IP keying, preserving single-IP abuse
-    // caps. A forged cookie hashes to a key with no cache entry → no uplift,
-    // no per-session escape.
+    // caps. A forged cookie hashes to a key with no cache entry, so it cannot
+    // escape the shared IP bucket.
     let trustEntry: CachedTrustEntry | null = null;
-    let sessionTrusted = false;
-    if (isRead && edgeTrustEnabled()) {
+    let sessionScoped = false;
+    if (edgeTrustEnabled()) {
       const lookupKeys = [
         identity.sessionKey,
-        identity.cidrKey,
-        identity.ipKey,
-        identity.workspaceKey,
+        ...(isRead
+          ? [identity.cidrKey, identity.ipKey, identity.workspaceKey]
+          : []),
       ].filter((key): key is string => key != null);
       const entries = await getCachedTrustEntries(lookupKeys);
 
       const sessionEntry = identity.sessionKey
         ? entries.get(identity.sessionKey)
         : undefined;
-      // Location/workspace trust applies to the shared per-IP bucket for the
-      // whole team; session trust applies to the per-session bucket.
-      const locationEntry = combineTrustEntries([
-        identity.cidrKey ? entries.get(identity.cidrKey) : undefined,
-        identity.ipKey ? entries.get(identity.ipKey) : undefined,
-        identity.workspaceKey ? entries.get(identity.workspaceKey) : undefined,
-      ]);
-
-      trustEntry = combineTrustEntries([sessionEntry, locationEntry]);
-      sessionTrusted = !!identity.sessionKey && !!sessionEntry;
+      sessionScoped = !!identity.sessionKey && !!sessionEntry;
+
+      if (isRead) {
+        // Location/workspace trust applies to the shared per-IP bucket for the
+        // whole team; session trust applies to the per-session bucket.
+        const locationEntry = combineTrustEntries([
+          identity.cidrKey ? entries.get(identity.cidrKey) : undefined,
+          identity.ipKey ? entries.get(identity.ipKey) : undefined,
+          identity.workspaceKey
+            ? entries.get(identity.workspaceKey)
+            : undefined,
+        ]);
+
+        trustEntry = combineTrustEntries([sessionEntry, locationEntry]);
+      }
     }
 
-    // Trusted sessions key per-session; everyone else keys per-IP.
+    // Server-verified sessions key per-session; everyone else keys per-IP.
     const limiterId =
-      sessionTrusted && identity.sessionKey
+      sessionScoped && identity.sessionKey
         ? identity.sessionKey
         : identity.ipKey;
 
     if (limiterId) {
-      const baseRateLimits = getEffectiveRateLimits(routePolicy, callerClass);
-      const { profile: rateLimits, suffix: trustSuffix } =
-        applyTrustEntryToReads(baseRateLimits, trustEntry);
+      const effectiveCallerClass: CallerClass = sessionScoped
+        ? 'authenticated'
+        : callerClass;
+      const baseRateLimits = getEffectiveRateLimits(
+        routePolicy,
+        effectiveCallerClass
+      );
+      const { profile: rateLimits, suffix: trustSuffix } = isRead
+        ? applyTrustEntryToReads(baseRateLimits, trustEntry)
+        : { profile: baseRateLimits, suffix: '' };
 
       const limiterPrefix = getRateLimitPrefix(
         options.prefixBase,
         routePolicy,
-        callerClass,
+        effectiveCallerClass,
         trustSuffix
       );
       const limiterCacheKey = `${limiterPrefix}:${JSON.stringify(rateLimits)}`;
@@ -1283,7 +1381,7 @@ export async function guardApiProxyRequest(
             'X-RateLimit-Limit': `${limit}`,
             'X-RateLimit-Remaining': `${remaining}`,
             'X-RateLimit-Reset': `${Math.ceil(reset / 1000)}`,
-            'X-RateLimit-Caller-Class': callerClass,
+            'X-RateLimit-Caller-Class': effectiveCallerClass,
             'X-RateLimit-Window': window,
             'X-RateLimit-Policy': routePolicy.key,
           });

package/src/currencies.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getCurrencyConfig,
+  getCurrencyLocale,
+  isSupportedCurrency,
+  resolveSupportedCurrency,
+} from './currencies';
+
+describe('resolveSupportedCurrency', () => {
+  it('normalizes supported currency codes', () => {
+    expect(resolveSupportedCurrency(' sgd ')).toBe('SGD');
+    expect(resolveSupportedCurrency('eur')).toBe('EUR');
+  });
+
+  it('uses a supported fallback for missing or unsupported values', () => {
+    expect(resolveSupportedCurrency(undefined, 'VND')).toBe('VND');
+    expect(resolveSupportedCurrency(null, 'EUR')).toBe('EUR');
+    expect(resolveSupportedCurrency('XYZ', 'SGD')).toBe('SGD');
+  });
+
+  it('falls back to USD when the fallback is unsupported', () => {
+    expect(resolveSupportedCurrency('', 'XYZ')).toBe('USD');
+    expect(resolveSupportedCurrency('ZZZ', 'XYZ')).toBe('USD');
+  });
+});
+
+describe('currency lookup normalization', () => {
+  it('trims currency codes before support and locale checks', () => {
+    expect(isSupportedCurrency(' vnd ')).toBe(true);
+    expect(getCurrencyLocale(' php ')).toBe('en-PH');
+    expect(getCurrencyConfig(' eur ')?.code).toBe('EUR');
+  });
+});

package/src/currencies.ts

@@ -66,9 +66,8 @@ export type CurrencyConfig = (typeof SUPPORTED_CURRENCIES)[number];
  * @returns The BCP 47 locale string for the currency
  */
 export function getCurrencyLocale(currency = 'VND'): string {
-  const found = SUPPORTED_CURRENCIES.find(
-    (c) => c.code === currency.toUpperCase()
-  );
+  const code = currency.trim().toUpperCase();
+  const found = SUPPORTED_CURRENCIES.find((c) => c.code === code);
   return found?.locale ?? 'en-US';
 }
 
@@ -81,7 +80,30 @@ export function getCurrencyLocale(currency = 'VND'): string {
 export function isSupportedCurrency(
   currency: string
 ): currency is SupportedCurrency {
-  return SUPPORTED_CURRENCIES.some((c) => c.code === currency.toUpperCase());
+  const code = currency.trim().toUpperCase();
+  return SUPPORTED_CURRENCIES.some((c) => c.code === code);
+}
+
+/**
+ * Normalize a currency code to the supported uppercase code set.
+ *
+ * @param value - The candidate currency code
+ * @param fallback - The fallback currency code when value is missing or unsupported
+ * @returns A supported currency code
+ */
+export function resolveSupportedCurrency(
+  value: string | null | undefined,
+  fallback: string = 'USD'
+): SupportedCurrency {
+  const normalizedFallback = fallback.trim().toUpperCase();
+  const safeFallback = isSupportedCurrency(normalizedFallback)
+    ? normalizedFallback
+    : 'USD';
+  const normalizedValue = value?.trim().toUpperCase();
+
+  return normalizedValue && isSupportedCurrency(normalizedValue)
+    ? normalizedValue
+    : safeFallback;
 }
 
 /**
@@ -93,5 +115,6 @@ export function isSupportedCurrency(
 export function getCurrencyConfig(
   currency: string
 ): CurrencyConfig | undefined {
-  return SUPPORTED_CURRENCIES.find((c) => c.code === currency.toUpperCase());
+  const code = currency.trim().toUpperCase();
+  return SUPPORTED_CURRENCIES.find((c) => c.code === code);
 }

package/src/effect.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from 'vitest';
+import {
+  Effect,
+  forEachConcurrently,
+  fromDataError,
+  fromPromise,
+  runEffectAsResult,
+  serializeTuturuuuEffectError,
+  TuturuuuEffectError,
+  toTuturuuuEffectError,
+  withTuturuuuRetry,
+  withTuturuuuTimeout,
+} from './effect';
+
+describe('@tuturuuu/utils/effect', () => {
+  it('creates tagged Tuturuuu errors with metadata', () => {
+    const error = new TuturuuuEffectError({
+      code: 'TEST_ERROR',
+      message: 'Test failed',
+      status: 418,
+      context: { feature: 'effect' },
+    });
+
+    expect(error._tag).toBe('TuturuuuEffectError');
+    expect(error.message).toBe('Test failed');
+    expect(serializeTuturuuuEffectError(error)).toEqual({
+      _tag: 'TuturuuuEffectError',
+      code: 'TEST_ERROR',
+      message: 'Test failed',
+      status: 418,
+      context: { feature: 'effect' },
+    });
+  });
+
+  it('normalizes unknown errors with fallback metadata', () => {
+    const error = toTuturuuuEffectError(new Error('Boom'), {
+      code: 'FALLBACK',
+      message: 'Fallback message',
+      status: 500,
+    });
+
+    expect(error).toBeInstanceOf(TuturuuuEffectError);
+    expect(error.code).toBe('FALLBACK');
+    expect(error.message).toBe('Boom');
+    expect(error.status).toBe(500);
+  });
+
+  it('converts data/error style operations into successful effects', async () => {
+    const result = await Effect.runPromise(
+      fromDataError(
+        () => Promise.resolve({ data: { id: 'row-1' }, error: null }),
+        {
+          code: 'DATA_ERROR',
+          message: 'Data read failed',
+        }
+      )
+    );
+
+    expect(result).toEqual({ id: 'row-1' });
+  });
+
+  it('converts data/error style failures into typed errors', async () => {
+    const result = await runEffectAsResult(
+      fromDataError(
+        () =>
+          Promise.resolve({
+            data: null,
+            error: {
+              code: 'PGRST116',
+              message: 'No row found',
+              details: 'Expected one row',
+            },
+          }),
+        {
+          code: 'DATA_ERROR',
+          message: 'Data read failed',
+        }
+      )
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'PGRST116',
+        message: 'No row found',
+        context: { details: 'Expected one row' },
+      },
+    });
+  });
+
+  it('converts rejected promises into typed errors', async () => {
+    const result = await runEffectAsResult(
+      fromPromise(() => Promise.reject(new Error('Network failed')), {
+        code: 'NETWORK_FAILED',
+        message: 'Request failed',
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatchObject({
+        _tag: 'TuturuuuEffectError',
+        code: 'NETWORK_FAILED',
+        message: 'Network failed',
+      });
+    }
+  });
+
+  it('returns success and failure result shapes', async () => {
+    await expect(runEffectAsResult(Effect.succeed('ok'))).resolves.toEqual({
+      ok: true,
+      data: 'ok',
+    });
+
+    await expect(
+      runEffectAsResult(
+        Effect.fail(
+          new TuturuuuEffectError({
+            code: 'EXPECTED_FAILURE',
+            message: 'Expected failure',
+          })
+        )
+      )
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'EXPECTED_FAILURE',
+        message: 'Expected failure',
+      },
+    });
+  });
+
+  it('retries expected failures with a typed retry predicate', async () => {
+    let attempts = 0;
+    const program = Effect.flatMap(
+      Effect.sync(() => {
+        attempts += 1;
+        return attempts;
+      }),
+      (attempt) =>
+        attempt < 3
+          ? Effect.fail(
+              new TuturuuuEffectError({
+                code: 'TRANSIENT_FAILURE',
+                message: 'Try again',
+              })
+            )
+          : Effect.succeed('ready')
+    );
+
+    await expect(
+      Effect.runPromise(
+        withTuturuuuRetry(program, {
+          times: 2,
+          while: (error) => error.code === 'TRANSIENT_FAILURE',
+        })
+      )
+    ).resolves.toBe('ready');
+    expect(attempts).toBe(3);
+  });
+
+  it('does not retry when the retry predicate rejects the error', async () => {
+    let attempts = 0;
+
+    const result = await runEffectAsResult(
+      withTuturuuuRetry(
+        Effect.flatMap(
+          Effect.sync(() => {
+            attempts += 1;
+          }),
+          () =>
+            Effect.fail(
+              new TuturuuuEffectError({
+                code: 'PERMANENT_FAILURE',
+                message: 'Do not retry',
+              })
+            )
+        ),
+        {
+          times: 3,
+          while: (error) => error.code === 'TRANSIENT_FAILURE',
+        }
+      )
+    );
+
+    expect(attempts).toBe(1);
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'PERMANENT_FAILURE',
+        message: 'Do not retry',
+      },
+    });
+  });
+
+  it('converts timeouts into Tuturuuu effect errors', async () => {
+    const result = await runEffectAsResult(
+      withTuturuuuTimeout(Effect.never, {
+        code: 'TIMED_OUT',
+        duration: 0,
+        message: 'Operation timed out',
+        context: { operation: 'test' },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'TIMED_OUT',
+        message: 'Operation timed out',
+        context: { operation: 'test' },
+      },
+    });
+  });
+
+  it('runs effectful collections with bounded concurrency', async () => {
+    let active = 0;
+    let maxActive = 0;
+
+    const result = await Effect.runPromise(
+      forEachConcurrently(
+        [1, 2, 3, 4],
+        (item) =>
+          Effect.promise(
+            () =>
+              new Promise<number>((resolve) => {
+                active += 1;
+                maxActive = Math.max(maxActive, active);
+
+                setTimeout(() => {
+                  active -= 1;
+                  resolve(item * 2);
+                }, 5);
+              })
+          ),
+        { concurrency: 2 }
+      )
+    );
+
+    expect(result).toEqual([2, 4, 6, 8]);
+    expect(maxActive).toBeLessThanOrEqual(2);
+  });
+});