payment-kit 1.29.1 → 1.29.3

package/api/src/libs/env.ts

@@ -1,68 +1,184 @@
 import { env } from '@blocklet/sdk/lib/env';
 
-export const paymentStatCronTime: string = '0 1 0 * * *'; // 默认每天一次，计算前一天的
-export const subscriptionCronTime: string = process.env.SUBSCRIPTION_CRON_TIME || '0 */30 * * * *'; // 默认每 30 min 行一次
-export const notificationCronTime: string = process.env.NOTIFICATION_CRON_TIME || '0 5 */6 * * *'; // 默认每6个小时执行一次
-export const expiredSessionCleanupCronTime: string = process.env.EXPIRED_SESSION_CLEANUP_CRON_TIME || '0 1 * * * *'; // 默认每小时执行一次
-export const notificationCronConcurrency: number = Number(process.env.NOTIFICATION_CRON_CONCURRENCY) || 8; // 默认并发数为 8
-export const stripeInvoiceCronTime: string = process.env.STRIPE_INVOICE_CRON_TIME || '0 */30 * * * *'; // 默认每 30min 执行一次
-export const stripePaymentCronTime: string = process.env.STRIPE_PAYMENT_CRON_TIME || '0 */20 * * * *'; // 默认每 20min 执行一次
-export const stripeSubscriptionCronTime: string = process.env.STRIPE_SUBSCRIPTION_CRON_TIME || '0 10 */8 * * *'; // 默认每 8小时 执行一次
-export const revokeStakeCronTime: string = process.env.REVOKE_STAKE_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
-export const daysUntilCancel: string | undefined = process.env.DAYS_UNTIL_CANCEL;
-export const meteringSubscriptionDetectionCronTime: string =
-  process.env.METERING_SUBSCRIPTION_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
-export const overdueDetectionCronTime: string = process.env.OVERDUE_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
-export const overdueThreshold: number = process.env.OVERDUE_THRESHOLD ? +process.env.OVERDUE_THRESHOLD : 5; // 默认超额阈值为 5
-export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
-export const creditConsumptionCronTime: string = process.env.CREDIT_CONSUMPTION_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const vendorStatusCheckCronTime: string = process.env.VENDOR_STATUS_CHECK_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const iapReconcileCronTime: string = process.env.IAP_RECONCILE_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次:webhook 兜底,拉 App Store / Google Play 订阅最新状态
-export const eventRetryCronTime: string = process.env.EVENT_RETRY_CRON_TIME || '30 */5 * * * *'; // 默认每 5 min 执行一次(错开整点避开 iap-reconcile):扫 pending_webhooks>0 的事件兜底投递
-export const quoteCleanupCronTime: string = process.env.QUOTE_CLEANUP_CRON_TIME || '0 0 2 * * *'; // 默认每天凌晨 2 点执行一次
-export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
-  ? +process.env.VENDOR_TIMEOUT_MINUTES
-  : 10; // 默认 10 分钟超时
-export const webhookAlertWindowMinutes: number = process.env.WEBHOOK_ALERT_WINDOW_MINUTES
-  ? +process.env.WEBHOOK_ALERT_WINDOW_MINUTES
-  : 10; // webhook 连续失败告警时间窗口，默认 10 分钟
-export const webhookAlertMinFailures: number = process.env.WEBHOOK_ALERT_MIN_FAILURES
-  ? +process.env.WEBHOOK_ALERT_MIN_FAILURES
-  : 3; // webhook 触发告警的最小失败次数，默认 3 次
-
-export const shortUrlApiKey: string = process.env.SHORT_URL_API_KEY || '';
-export const shortUrlDomain: string = process.env.SHORT_URL_DOMAIN || 's.abtnet.io';
+// ──────────────────────────────────────────────────────────────────────────
+// Phase 8 (W2′): the injected-config slot, made authoritative here.
+//
+// libs/env.ts is the ONE module the core-env scanner exempts — the single
+// allowed reader of process.env / the CF env mirror. Phase 8 converges every
+// scattered `process.env.X` read in api/src INTO the accessors below so the
+// whitelist goes to zero.
+//
+// The factory (createEmbeddedPaymentService) calls setCoreConfig(config) so the
+// injected config object becomes the source of truth. Reads fall back to
+// process.env when a key is absent from the injected config — which keeps every
+// host working unchanged: the blocklet server populates process.env natively,
+// and the CF worker mirrors CF env into process.env per request (that mirror is
+// deleted in Phase 12, once the worker routes through the factory config slot).
+// ──────────────────────────────────────────────────────────────────────────
+let activeConfig: Record<string, any> | undefined;
+
+/** Wire the injected config object (factory only). Pass undefined to clear (tests). */
+export function setCoreConfig(config: Record<string, any> | undefined): void {
+  activeConfig = config;
+}
+
+/** The injected config object, or undefined before the factory has run. */
+export function getCoreConfig(): Record<string, any> | undefined {
+  return activeConfig;
+}
+
+/**
+ * Read a config key: the injected config wins; otherwise the process.env
+ * fallback (blocklet server native / worker mirror). Returns a string or
+ * undefined — callers parse/typecheck. This is the single boundary read.
+ */
+export function readConfig(key: string): string | undefined {
+  const injected = activeConfig?.[key];
+  if (injected !== undefined && injected !== null) return String(injected);
+  const fromEnv = process.env[key];
+  return fromEnv === undefined ? undefined : fromEnv;
+}
+
+/** True iff the key is present (non-empty) in injected config or process.env. */
+export function hasConfig(key: string): boolean {
+  const v = readConfig(key);
+  return v !== undefined && v !== '';
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// P1 (9a review fix): these were import-time `process.env` consts — frozen
+// before the factory could setCoreConfig, so injected config could never
+// override them (now that 9a bundles the canonical core into the published
+// package, that mattered for arc). They are LAZY getters now, reading via the
+// readConfig boundary, honored at call time. Consumers call them at use time.
+// ──────────────────────────────────────────────────────────────────────────
+const numConfig = (key: string, fallback: number): number => {
+  const v = readConfig(key);
+  return v ? +v : fallback;
+};
+
+export const paymentStatCronTime = (): string => '0 1 0 * * *'; // 默认每天一次，计算前一天的
+export const subscriptionCronTime = (): string => readConfig('SUBSCRIPTION_CRON_TIME') || '0 */30 * * * *';
+export const notificationCronTime = (): string => readConfig('NOTIFICATION_CRON_TIME') || '0 5 */6 * * *';
+export const expiredSessionCleanupCronTime = (): string =>
+  readConfig('EXPIRED_SESSION_CLEANUP_CRON_TIME') || '0 1 * * * *';
+export const notificationCronConcurrency = (): number => Number(readConfig('NOTIFICATION_CRON_CONCURRENCY')) || 8;
+export const stripeInvoiceCronTime = (): string => readConfig('STRIPE_INVOICE_CRON_TIME') || '0 */30 * * * *';
+export const stripePaymentCronTime = (): string => readConfig('STRIPE_PAYMENT_CRON_TIME') || '0 */20 * * * *';
+export const stripeSubscriptionCronTime = (): string => readConfig('STRIPE_SUBSCRIPTION_CRON_TIME') || '0 10 */8 * * *';
+export const revokeStakeCronTime = (): string => readConfig('REVOKE_STAKE_CRON_TIME') || '0 */5 * * * *';
+export const daysUntilCancel = (): string | undefined => readConfig('DAYS_UNTIL_CANCEL');
+export const meteringSubscriptionDetectionCronTime = (): string =>
+  readConfig('METERING_SUBSCRIPTION_DETECTION_CRON_TIME') || '0 0 10 * * *';
+export const overdueDetectionCronTime = (): string => readConfig('OVERDUE_DETECTION_CRON_TIME') || '0 0 10 * * *';
+export const overdueThreshold = (): number => numConfig('OVERDUE_THRESHOLD', 5);
+export const depositVaultCronTime = (): string => readConfig('DEPOSIT_VAULT_CRON_TIME') || '0 */5 * * * *';
+export const creditConsumptionCronTime = (): string => readConfig('CREDIT_CONSUMPTION_CRON_TIME') || '0 */10 * * * *';
+export const vendorStatusCheckCronTime = (): string => readConfig('VENDOR_STATUS_CHECK_CRON_TIME') || '0 */10 * * * *';
+export const vendorReturnScanCronTime = (): string => readConfig('VENDOR_RETURN_SCAN_CRON_TIME') || '0 */10 * * * *';
+export const iapReconcileCronTime = (): string => readConfig('IAP_RECONCILE_CRON_TIME') || '0 */5 * * * *';
+export const eventRetryCronTime = (): string => readConfig('EVENT_RETRY_CRON_TIME') || '30 */5 * * * *';
+export const quoteCleanupCronTime = (): string => readConfig('QUOTE_CLEANUP_CRON_TIME') || '0 0 2 * * *';
+export const vendorTimeoutMinutes = (): number => numConfig('VENDOR_TIMEOUT_MINUTES', 10);
+export const webhookAlertWindowMinutes = (): number => numConfig('WEBHOOK_ALERT_WINDOW_MINUTES', 10);
+export const webhookAlertMinFailures = (): number => numConfig('WEBHOOK_ALERT_MIN_FAILURES', 3);
+
+export const shortUrlApiKey = (): string => readConfig('SHORT_URL_API_KEY') || '';
+export const shortUrlDomain = (): string => readConfig('SHORT_URL_DOMAIN') || 's.abtnet.io';
 
 // sequelize 配置相关
-export const sequelizeOptionsPoolMin: number = process.env.SEQUELIZE_OPTIONS_POOL_MIN
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_MIN
-  : 0;
-export const sequelizeOptionsPoolMax: number = process.env.SEQUELIZE_OPTIONS_POOL_MAX
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_MAX
-  : 5;
-export const sequelizeOptionsPoolIdle: number = process.env.SEQUELIZE_OPTIONS_POOL_IDLE
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_IDLE
-  : 10 * 1000;
-
-export const updateDataConcurrency: number = process.env.UPDATE_DATA_CONCURRENCY
-  ? +process.env.UPDATE_DATA_CONCURRENCY
-  : 5; // 默认并发数为 5
+export const sequelizeOptionsPoolMin = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_MIN', 0);
+export const sequelizeOptionsPoolMax = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_MAX', 5);
+export const sequelizeOptionsPoolIdle = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_IDLE', 10 * 1000);
+
+export const updateDataConcurrency = (): number => numConfig('UPDATE_DATA_CONCURRENCY', 5);
 
 // When set to 'true' or '1', the system stops accepting new orders.
 // Existing checkout sessions can still be viewed but new submissions will be rejected.
-export const stopAcceptingOrders: boolean =
-  process.env.PAYMENT_KIT_STOP_ACCEPTING_ORDERS === 'true' || process.env.PAYMENT_KIT_STOP_ACCEPTING_ORDERS === '1';
+export const stopAcceptingOrders = (): boolean =>
+  readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === 'true' || readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === '1';
 
-export const exchangeRateCacheTTLSeconds: number = process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
-  ? +process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
-  : 10 * 60;
+export const exchangeRateCacheTTLSeconds = (): number => numConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS', 10 * 60);
 
 // System-level maximum pending amount limit (in token format, e.g., "10")
 // Default is 0 (disabled). Set PAYMENT_KIT_MAX_PENDING_AMOUNT to enable this limit.
-export const systemMaxPendingAmount: number = process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT
-  ? +process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT
-  : 5;
+export const systemMaxPendingAmount = (): number => numConfig('PAYMENT_KIT_MAX_PENDING_AMOUNT', 5);
+
+// Whether a locked price may still be edited. Lazy (reads injected config via
+// the boundary at call time) like every other Phase 8 accessor.
+export const allowChangeLockedPrice = (): boolean => readConfig('PAYMENT_CHANGE_LOCKED_PRICE') === '1';
+
+// ──────────────────────────────────────────────────────────────────────────
+// Phase 8 (W2′): converged accessors. Every read below used to live inline in
+// api/src as a direct process.env / __CF_ENV__ access (the 57-entry whitelist).
+// They are LAZY (functions, not import-time consts) so the injected config —
+// wired by the factory AFTER module import — is honored at call time, and so
+// tests that flip process.env at runtime keep working.
+// ──────────────────────────────────────────────────────────────────────────
+
+// -- runtime mode / environment --
+export const blockletMode = (): string | undefined => readConfig('BLOCKLET_MODE');
+export const isProduction = (): boolean => blockletMode() === 'production';
+export const nodeEnv = (): string | undefined => readConfig('NODE_ENV');
+export const isTestEnv = (): boolean => nodeEnv() === 'test';
+export const isDevelopmentEnv = (): boolean => nodeEnv() === 'development';
+export const enableDevFakeAuth = (): boolean => readConfig('ENABLE_DEV_FAKE_AUTH') === '1';
+
+// -- tenant mode-source (getTenantMode / getDefaultInstanceDid read these) --
+export const tenantModeRaw = (): string | undefined => readConfig('PAYMENT_TENANT_MODE');
+export const blockletAppPid = (): string | undefined => readConfig('BLOCKLET_APP_PID');
+
+// -- app identity / urls --
+export const blockletAppId = (): string | undefined => readConfig('BLOCKLET_APP_ID');
+export const blockletAppName = (): string | undefined => readConfig('BLOCKLET_APP_NAME');
+export const blockletAppUrl = (): string | undefined => readConfig('BLOCKLET_APP_URL');
+export const blockletAppHost = (): string | undefined => readConfig('BLOCKLET_APP_HOST');
+export const blockletAppDir = (): string | undefined => readConfig('BLOCKLET_APP_DIR');
+export const blockletPort = (): string | undefined => readConfig('BLOCKLET_PORT');
+export const blockletMountPoints = (): string | undefined => readConfig('BLOCKLET_MOUNT_POINTS');
+
+// -- integrations --
+export const appStoreWriteEnabled = (): boolean => readConfig('APP_STORE_WRITE_ENABLED') === 'true';
+export const appStoreSkipSignatureVerify = (): boolean => readConfig('APP_STORE_SKIP_SIGNATURE_VERIFY') === 'true';
+export const googlePubsubSkipSignatureVerify = (): boolean =>
+  readConfig('GOOGLE_PUBSUB_SKIP_SIGNATURE_VERIFY') === 'true';
+export const googlePubsubPushServiceAccount = (): string | undefined =>
+  readConfig('GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT');
+export const googlePubsubAllowUnverifiedSender = (): boolean =>
+  readConfig('GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER') === 'true';
+export const googlePlayWebhookUrl = (): string | undefined => readConfig('GOOGLE_PLAY_WEBHOOK_URL');
+export const stripeWebhookSecret = (): string | undefined => readConfig('STRIPE_WEBHOOK_SECRET');
+export const iapReconcileBatchSize = (): number => Number(readConfig('IAP_RECONCILE_BATCH_SIZE') ?? '100');
+
+// -- payment params --
+export const paymentBillingThreshold = (): number => +(readConfig('PAYMENT_BILLING_THRESHOLD') as string);
+export const paymentMinStakeAmount = (): number => +(readConfig('PAYMENT_MIN_STAKE_AMOUNT') as string);
+export const paymentDaysUntilDue = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_DUE');
+export const paymentDaysUntilCancel = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_CANCEL');
+export const paymentReloadSubscriptionJobs = (): boolean => readConfig('PAYMENT_RELOAD_SUBSCRIPTION_JOBS') === '1';
+export const paymentRateVolatilityThreshold = (): string | undefined => readConfig('PAYMENT_RATE_VOLATILITY_THRESHOLD');
+export const paymentLivemode = (): boolean => readConfig('PAYMENT_LIVEMODE') !== 'false';
+
+// -- credit queue --
+export const creditLowBalanceThresholdPercentage = (): number =>
+  parseInt(readConfig('CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE') || '10', 10);
+export const creditBatchSize = (): number => Math.max(1, parseInt(readConfig('CREDIT_BATCH_SIZE') || '50', 10));
+export const creditBatchWindowMs = (): number =>
+  Math.max(10, parseInt(readConfig('CREDIT_BATCH_WINDOW_MS') || '3000', 10));
+export const creditQueueConcurrency = (): number =>
+  Math.max(1, Math.min(20, parseInt(readConfig('CREDIT_QUEUE_CONCURRENCY') || '5', 10) || 5));
+
+// -- exchange rate cache TTL source (the value itself is exchangeRateCacheTTLSeconds above) --
+export const exchangeRateCacheTTLFromEnv = (): boolean => hasConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS');
+
+// -- store / sequelize logging --
+export const sqlLog = (): boolean => readConfig('SQL_LOG') === '1';
+export const sqlBenchmark = (): boolean => readConfig('SQL_BENCHMARK') === '1';
+
+// -- CF worker runtime detection + env mirror (set by cloudflare/worker.ts on
+//    globalThis; the boundary so core never reads the global directly) --
+export const cfEnv = (): any => (globalThis as any).__CF_ENV__;
+export const isCfWorker = (): boolean => !!cfEnv();
 
 export default {
   ...env,

package/api/src/libs/exchange-rate/service.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-await-in-loop */
 import BigNumber from 'bignumber.js';
+import { exchangeRateCacheTTLFromEnv, exchangeRateCacheTTLSeconds } from '../env';
 import { ExchangeRateProvider } from '../../store/models/exchange-rate-provider';
 import logger from '../logger';
 import { events } from '../event';
@@ -8,15 +9,15 @@ import { SymbolNotSupportedError } from './types';
 import { TokenDataProvider } from './token-data-provider';
 import { CoinGeckoProvider } from './coingecko-provider';
 import { CoinMarketCapProvider } from './coinmarketcap-provider';
-import { exchangeRateCacheTTLSeconds } from '../env';
 
 interface CacheEntry {
   data: ExchangeRateResult;
   timestamp: number;
 }
 
-// Cache TTL from environment variable, default 10 minutes
-const CACHE_TTL_MS = (exchangeRateCacheTTLSeconds || 10 * 60) * 1000;
+// Cache TTL from config, default 10 minutes. Lazy so injected config (set after
+// module import) is honored — not frozen in a module-level const.
+const cacheTtlMs = (): number => (exchangeRateCacheTTLSeconds() || 10 * 60) * 1000;
 const MAX_RATE_AGE_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_DEVIATION_PERCENT = 5; // 5%
 const HISTORY_WINDOW_SIZE = 10;
@@ -185,7 +186,7 @@ export class ExchangeRateService {
 
     // Check cache first
     const cached = this.cache.get(cacheKey);
-    if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    if (cached && Date.now() - cached.timestamp < cacheTtlMs()) {
       logger.debug('Exchange rate cache hit', { symbol, age: Date.now() - cached.timestamp });
       return cached.data;
     }
@@ -575,8 +576,8 @@ export function getExchangeRateService(): ExchangeRateService {
   if (!serviceInstance) {
     serviceInstance = new ExchangeRateService();
     logger.info('Exchange rate service initialized', {
-      cache_ttl_seconds: CACHE_TTL_MS / 1000,
-      cache_ttl_source: process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS ? 'env' : 'default',
+      cache_ttl_seconds: cacheTtlMs() / 1000,
+      cache_ttl_source: exchangeRateCacheTTLFromEnv() ? 'env' : 'default',
     });
   }
   return serviceInstance;

package/api/src/libs/http-fetch-adapter.ts

@@ -0,0 +1,60 @@
+// D5 — the Web-Fetch entry for hosts that own their own app shell (arc-node's
+// registerPrefixHandler): `svc.http.fetch(req, {basePath})` with no express bridge.
+//
+// Phase 4 (express→hono): the loopback http.Server + express app are gone, so this
+// is just a base-strip wrapper over `honoApp.fetch`. The outward signature +
+// strip semantics are unchanged (arc consumes this contract); raw-body fidelity
+// (Stripe webhook signature) holds because the stripped path reuses the exact
+// request bytes/headers, and status/Set-Cookie/redirect come from the hono Response.
+
+import type { Hono } from 'hono';
+
+/** Options for svc.http.fetch — basePath is stripped to reach the internal /api/*. */
+export interface PaymentFetchOptions {
+  /** the host's mount prefix (e.g. "/.well-known/payment"); stripped, no alias special-case */
+  basePath?: string;
+}
+
+export interface FetchHandler {
+  (request: Request, opts?: PaymentFetchOptions): Promise<Response>;
+  /** teardown hook (host lifecycle). No-op now that there is no loopback server. */
+  close(): Promise<void>;
+}
+
+export function createFetchHandler(app: Hono): FetchHandler {
+  const handler = (async (request: Request, opts?: PaymentFetchOptions): Promise<Response> => {
+    const url = new URL(request.url);
+
+    // ① base-strip: remove basePath → internal /api/* path (no alias special-case).
+    //    Precise segment-boundary check (=== basePath || startsWith(basePath + '/'))
+    //    so "/foo" never matches "/foobar" — byte-identical to the old loopback strip.
+    const basePath = opts?.basePath ?? '';
+    if (basePath && (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`))) {
+      url.pathname = url.pathname.slice(basePath.length) || '/';
+      // ② rebuild the request at the stripped URL. The body is read ONCE into a
+      //    fixed buffer (raw bytes preserved for Stripe webhook signature) and the
+      //    original headers/method are carried verbatim (Host preserved).
+      const method = request.method.toUpperCase();
+      const hasBody = method !== 'GET' && method !== 'HEAD';
+      const body = hasBody ? await request.arrayBuffer() : undefined;
+      // ③ re-expose the stripped mount prefix as `x-path-prefix` so internal
+      //    absolute-URL builders reconstruct the PUBLIC url. The DID-Connect
+      //    authenticator's wallet callback URL is built by did-connect-js
+      //    `prepareBaseUrl`, which reads `x-path-prefix`; without it the wallet is
+      //    told to call <origin>/api/did/payment/auth instead of
+      //    <origin><basePath>/api/did/payment/auth and the connect times out. The
+      //    Request's headers are immutable, so set it on a fresh Headers; never
+      //    clobber a host-provided value (blocklet-server sets its own mount).
+      const headers = new Headers(request.headers);
+      if (!headers.has('x-path-prefix')) headers.set('x-path-prefix', basePath);
+      return app.fetch(new Request(url.toString(), { method, headers, body }));
+    }
+
+    // no strip needed — hand the request straight to hono (it owns body parsing).
+    return app.fetch(request);
+  }) as FetchHandler;
+
+  handler.close = (): Promise<void> => Promise.resolve();
+
+  return handler;
+}

package/api/src/libs/invoice.ts

@@ -1,4 +1,4 @@
-import { component } from '@blocklet/sdk';
+import component from '@blocklet/sdk/lib/component';
 import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 

package/api/src/libs/lock.ts

@@ -1,53 +1,57 @@
-const { EventEmitter } = require('events');
-
-export class Lock {
-  name: string;
-  locked: boolean;
-  events: typeof EventEmitter;
-
-  constructor(name: string) {
-    this.name = name;
-    this.locked = false;
-    this.events = new EventEmitter();
-  }
-
-  acquire() {
-    return new Promise((resolve) => {
-      // If somebody has the lock, wait until he/she releases the lock and try again
-      if (this.locked) {
-        const tryAcquire = () => {
-          if (!this.locked) {
-            this.locked = true;
-            this.events.removeListener('release', tryAcquire);
-            resolve(true);
-          }
-        };
+// Phase 8 (W2-1a): lock facade over the locks slot driver.
+//
+// Call sites keep using `getLock(name)` unchanged. Behind the facade:
+//   - the active locks driver is injectable (`setLocksDriver`) — default is the
+//     in-process memory driver (Blocklet Server / Node). The worker injects the
+//     D1 driver through the locks slot.
+//   - lock names are tenant-prefixed (W1 §2.2) by default. Per-resource locks
+//     are tenant-scoped; process-level singleton guards (queue start guards,
+//     recovery) opt out with `{ scope: 'global' }`. In single-tenant mode the
+//     prefix is the constant deployment app DID, so lock identity is unchanged.
+
+import { getInstanceDid } from './context';
+import {
+  createMemoryLocksDriver,
+  scopedLockName,
+  MemoryLock,
+  type LockHandle,
+  type LocksDriver,
+  type LockScope,
+} from './drivers';
+
+let activeDriver: LocksDriver = createMemoryLocksDriver();
+
+/** Inject the locks driver (worker wires the D1 driver here). */
+export function setLocksDriver(driver: LocksDriver): void {
+  activeDriver = driver;
+}
 
-        this.events.on('release', tryAcquire);
-      } else {
-        // Otherwise, take the lock and resolve immediately
-        this.locked = true;
-        resolve(true);
-      }
-    });
-  }
+export function getLocksDriver(): LocksDriver {
+  return activeDriver;
+}
 
-  release() {
-    // Release the lock immediately
-    this.locked = false;
-    setImmediate(() => this.events.emit('release'));
-  }
+export interface GetLockOptions {
+  ttl?: number;
+  /** 'tenant' (default) prefixes the lock name with the current tenant; 'global' keeps the bare name. */
+  scope?: LockScope;
 }
 
-const locks = new Map<string, Lock>();
-export function getLock(name: string): Lock {
-  const exist = locks.get(name);
-  if (exist instanceof Lock) {
-    return exist;
+/**
+ * Acquire a handle to a named lock. Tenant-scoped by default; resolving the
+ * tenant fails closed in multi-tenant mode when no context is present (matching
+ * the scoped-query helpers from Phase 3).
+ */
+export function getLock(name: string, options: GetLockOptions = {}): LockHandle {
+  if (!name || typeof name !== 'string') {
+    throw new Error('getLock: a non-empty lock name is required');
   }
-
-  const lock = new Lock(name);
-  locks.set(name, lock);
-
-  return lock;
+  const scope: LockScope = options.scope ?? 'tenant';
+  const instanceDid = scope === 'tenant' ? getInstanceDid() : null;
+  const resolvedName = scopedLockName(name, instanceDid, scope);
+  return activeDriver.getLock(resolvedName, options.ttl !== undefined ? { ttl: options.ttl } : undefined);
 }
+
+// `Lock` is the in-process memory lock class — kept as a public export so the
+// standalone constructor form (`new Lock(name)`) and `LockHandle` annotations
+// both keep working.
+export { MemoryLock as Lock };

package/api/src/libs/logger.ts

@@ -1,4 +1,13 @@
-const createLogger = require('@blocklet/logger');
+// Phase 13b: lazy logging boundary.
+//
+// @blocklet/logger throws at REQUIRE time when BLOCKLET_LOG_DIR is absent
+// ("valid BLOCKLET_LOG_DIR env is required by logger"). That made importing the
+// core — and therefore createEmbeddedPaymentService / rpc.entitlements.check,
+// which transitively import this module — demand a blocklet log env even for a
+// bare host (arc embedding before its blocklet runtime is wired). Defer the
+// require to first use and fall back to console when no blocklet log env exists.
+// The blocklet server (BLOCKLET_LOG_DIR set) and the CF worker (aliased shim)
+// still get the real logger on first call — behavior unchanged for them.
 
 interface Logger {
   debug: (...args: any[]) => void;
@@ -7,14 +16,45 @@ interface Logger {
   warn: (...args: any[]) => void;
 }
 
-const init = (label: string): Logger => {
-  const instance = createLogger(label || '');
-  return instance;
-};
+let resolved: Logger | undefined;
 
-const logger = init('app');
+function resolveLogger(): Logger {
+  if (resolved) return resolved;
+  try {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    const createLogger = require('@blocklet/logger');
+    resolved = createLogger('app') as Logger;
+  } catch {
+    // bare host without a blocklet log env — console fallback.
+    /* eslint-disable no-console */
+    resolved = {
+      debug: (...args: any[]) => console.debug(...args),
+      info: (...args: any[]) => console.info(...args),
+      error: (...args: any[]) => console.error(...args),
+      warn: (...args: any[]) => console.warn(...args),
+    };
+    /* eslint-enable no-console */
+  }
+  return resolved;
+}
+
+const logger: Logger = {
+  debug: (...args: any[]) => resolveLogger().debug(...args),
+  info: (...args: any[]) => resolveLogger().info(...args),
+  error: (...args: any[]) => resolveLogger().error(...args),
+  warn: (...args: any[]) => resolveLogger().warn(...args),
+};
 
 export default logger;
 
-const { setupAccessLogger } = createLogger;
-export { setupAccessLogger };
+// Express access logger — also lazy. A bare host that never mounts the node
+// handler (where setupAccessLogger runs) never needs the blocklet log env.
+export function setupAccessLogger(app: any): void {
+  try {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    const createLogger = require('@blocklet/logger');
+    createLogger.setupAccessLogger?.(app);
+  } catch {
+    // bare host: no access logging
+  }
+}

package/api/src/libs/notification/index.ts

@@ -1,4 +1,4 @@
-import { Notification as BlockletNotification } from '@blocklet/sdk';
+import BlockletNotification from '@blocklet/sdk/service/notification';
 
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './template/base';
 import { CheckoutSession, CreditGrant, Invoice, Meter, MeterEvent, Subscription } from '../../store/models';

package/api/src/libs/notification/template/customer-credit-low-balance.ts

@@ -2,6 +2,7 @@
 /* eslint-disable @typescript-eslint/indent */
 import { withQuery } from 'ufo';
 import { BN } from '@ocap/util';
+import { creditLowBalanceThresholdPercentage } from '../../env';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import { Customer, PaymentCurrency, CreditGrant } from '../../../store/models';
@@ -35,7 +36,7 @@ export class CustomerCreditLowBalanceEmailTemplate implements BaseEmailTemplate<
    * @returns threshold percentage (default: 10)
    */
   static getLowBalanceThresholdPercent(): number {
-    return parseInt(process.env.CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE || '10', 10);
+    return creditLowBalanceThresholdPercentage();
   }
 
   /**

package/api/src/libs/notification/template/customer-revenue-succeeded.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/brace-style */
 /* eslint-disable @typescript-eslint/indent */
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import { CheckoutSession, Customer, PaymentLink, PaymentMethod, Payout } from '../../../store/models';

package/api/src/libs/notification/template/customer-reward-succeeded.ts

@@ -4,7 +4,7 @@ import isEmpty from 'lodash/isEmpty';
 import pWaitFor from 'p-wait-for';
 import type { LiteralUnion } from 'type-fest';
 
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import {

package/api/src/libs/overdraft-protection.ts

@@ -1,4 +1,4 @@
-import { createProductAndPrices } from '../routes/products';
+import { createProductAndPrices } from '../routes/hono/products';
 import { PaymentCurrency, PaymentMethod, Price, Product } from '../store/models';
 import logger from './logger';
 

package/api/src/libs/payout.ts

@@ -1,4 +1,4 @@
-import { component } from '@blocklet/sdk';
+import component from '@blocklet/sdk/lib/component';
 import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 import { getConnectQueryParam } from './util';