@omen.foundation/node-microservice-runtime 0.1.0

package/src/inventory.ts

@@ -0,0 +1,491 @@
+import { randomUUID } from 'node:crypto';
+import type { Logger } from 'pino';
+import type { BoundBeamApi } from './services.js';
+import { MissingScopesError } from './errors.js';
+
+export interface CurrencyProperty {
+  name: string;
+  value: string;
+}
+
+interface ItemProperty {
+  name: string;
+  value: string;
+}
+
+interface ItemCreateRequest {
+  contentId: string;
+  properties: ItemProperty[];
+  reqId?: string;
+}
+
+interface ItemDeleteRequest {
+  contentId: string;
+  id: string;
+}
+
+interface ItemUpdateRequest {
+  contentId: string;
+  id: string;
+  properties: ItemProperty[];
+}
+
+interface CurrencyView {
+  id: string;
+  amount: string | number | bigint;
+}
+
+export interface InventoryView {
+  currencies?: CurrencyView[];
+}
+
+export interface PreviewVipBonusResponse {
+  currencies: Array<{ id: string; amount: string | number | bigint; originalAmount?: string | number | bigint }>;
+}
+
+export interface MultipliersGetResponse {
+  [key: string]: unknown;
+}
+
+interface TransferRequestPayload {
+  recipientPlayer: string;
+  currencies?: Record<string, string>;
+  transaction?: string;
+}
+
+export interface InventoryUpdatePayload {
+  transaction?: string;
+  applyVipBonus?: boolean;
+  currencies?: Record<string, string>;
+  currencyProperties?: Record<string, CurrencyProperty[]>;
+  newItems?: Array<ItemCreateRequest>;
+  deleteItems?: Array<ItemDeleteRequest>;
+  updateItems?: Array<ItemUpdateRequest>;
+}
+
+export interface InventoryCurrencyChanges {
+  [currencyId: string]: bigint;
+}
+
+export interface InventoryBuilderOptions {
+  transaction?: string;
+}
+
+export class InventoryUpdateBuilder {
+  private readonly currencyChanges: Map<string, bigint> = new Map();
+  private readonly currencyPropertyUpdates: Map<string, CurrencyProperty[]> = new Map();
+  private readonly newItemRequests: Array<ItemCreateRequest & { reqId: string }> = [];
+  private readonly deleteItemRequests: ItemDeleteRequest[] = [];
+  private readonly updateItemRequests: ItemUpdateRequest[] = [];
+  private applyVipBonusFlag?: boolean;
+
+  applyVipBonus(apply: boolean): this {
+    this.applyVipBonusFlag = apply;
+    return this;
+  }
+
+  currencyChange(currencyId: string, delta: bigint | number): this {
+    const normalizedId = this.normalizeId(currencyId, 'currency');
+    const current = this.currencyChanges.get(normalizedId) ?? BigInt(0);
+    const next = current + BigInt(delta);
+    if (next === BigInt(0)) {
+      this.currencyChanges.delete(normalizedId);
+    } else {
+      this.currencyChanges.set(normalizedId, next);
+    }
+    return this;
+  }
+
+  setCurrencyProperties(currencyId: string, properties: CurrencyProperty[]): this {
+    const normalizedId = this.normalizeId(currencyId, 'currency');
+    this.currencyPropertyUpdates.set(normalizedId, [...properties]);
+    return this;
+  }
+
+  addItem(contentId: string, properties: Record<string, string> = {}, requestId: string = randomUUID()): this {
+    const normalizedId = this.normalizeId(contentId, 'item');
+    const itemProperties = Object.entries(properties).map<ItemProperty>(([name, value]) => ({
+      name,
+      value,
+    }));
+    this.newItemRequests.push({
+      contentId: normalizedId,
+      properties: itemProperties,
+      reqId: requestId,
+    });
+    return this;
+  }
+
+  deleteItem(contentId: string, itemId: bigint | number | string): this {
+    const normalizedId = this.normalizeId(contentId, 'item');
+    this.deleteItemRequests.push({
+      contentId: normalizedId,
+      id: this.toIdentifier(itemId),
+    });
+    return this;
+  }
+
+  updateItem(contentId: string, itemId: bigint | number | string, properties: Record<string, string>): this {
+    const normalizedId = this.normalizeId(contentId, 'item');
+    const normalizedProperties = Object.entries(properties).map<ItemProperty>(([name, value]) => ({
+      name,
+      value,
+    }));
+    this.updateItemRequests.push({
+      contentId: normalizedId,
+      id: this.toIdentifier(itemId),
+      properties: normalizedProperties,
+    });
+    return this;
+  }
+
+  merge(other: InventoryUpdateBuilder): this {
+    for (const [currencyId, delta] of other.currencyChanges.entries()) {
+      this.currencyChange(currencyId, delta);
+    }
+    for (const [currencyId, props] of other.currencyPropertyUpdates.entries()) {
+      this.currencyPropertyUpdates.set(currencyId, [...props]);
+    }
+    for (const item of other.newItemRequests) {
+      this.newItemRequests.push({ ...item });
+    }
+    for (const item of other.deleteItemRequests) {
+      this.deleteItemRequests.push({ ...item });
+    }
+    for (const item of other.updateItemRequests) {
+      this.updateItemRequests.push({
+        contentId: item.contentId,
+        id: this.toIdentifier(item.id),
+        properties: [...item.properties],
+      });
+    }
+    if (other.applyVipBonusFlag !== undefined) {
+      this.applyVipBonusFlag = other.applyVipBonusFlag;
+    }
+    return this;
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.currencyChanges.size === 0 &&
+      this.currencyPropertyUpdates.size === 0 &&
+      this.newItemRequests.length === 0 &&
+      this.deleteItemRequests.length === 0 &&
+      this.updateItemRequests.length === 0 &&
+      this.applyVipBonusFlag === undefined
+    );
+  }
+
+  toRequest(options: InventoryBuilderOptions = {}): InventoryUpdatePayload {
+    const payload: InventoryUpdatePayload = {};
+
+    if (options.transaction) {
+      payload.transaction = options.transaction;
+    }
+    if (this.applyVipBonusFlag !== undefined) {
+      payload.applyVipBonus = this.applyVipBonusFlag;
+    }
+    if (this.currencyChanges.size > 0) {
+      const currencies: Record<string, string> = {};
+      for (const [currencyId, delta] of this.currencyChanges.entries()) {
+        currencies[currencyId] = delta.toString();
+      }
+      payload.currencies = currencies;
+    }
+    if (this.currencyPropertyUpdates.size > 0) {
+      const currencyProperties: Record<string, CurrencyProperty[]> = {};
+      for (const [currencyId, properties] of this.currencyPropertyUpdates.entries()) {
+        currencyProperties[currencyId] = properties.map<CurrencyProperty>((property) => ({ ...property }));
+      }
+      payload.currencyProperties = currencyProperties;
+    }
+    if (this.newItemRequests.length > 0) {
+      payload.newItems = this.newItemRequests.map((item) => ({
+        contentId: item.contentId,
+        properties: item.properties.map<ItemProperty>((property) => ({ ...property })),
+        reqId: item.reqId,
+      }));
+    }
+    if (this.deleteItemRequests.length > 0) {
+      payload.deleteItems = this.deleteItemRequests.map((item) => ({
+        contentId: item.contentId,
+        id: this.toIdentifier(item.id),
+      }));
+    }
+    if (this.updateItemRequests.length > 0) {
+      payload.updateItems = this.updateItemRequests.map((item) => ({
+        contentId: item.contentId,
+        id: this.toIdentifier(item.id),
+        properties: item.properties.map<ItemProperty>((property) => ({ ...property })),
+      }));
+    }
+
+    return payload;
+  }
+
+  private normalizeId(value: string, kind: 'currency' | 'item'): string {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error(`Invalid ${kind} identifier: "${value}"`);
+    }
+    return trimmed;
+  }
+
+  private toIdentifier(value: bigint | number | string): string {
+    if (typeof value === 'bigint') {
+      return value.toString();
+    }
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) {
+        throw new Error(`Invalid numeric identifier: ${value}`);
+      }
+      return Math.trunc(value).toString();
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error('Identifier cannot be empty.');
+    }
+    return trimmed;
+  }
+}
+
+interface InventoryServiceDependencies {
+  api: BoundBeamApi;
+  logger: Logger;
+  userId: string;
+  scopeChecker: (scopes: string[]) => void;
+}
+
+export class InventoryService {
+  private readonly api: BoundBeamApi;
+  private readonly logger: Logger;
+  private readonly userId: string;
+  private readonly ensureScopes: (scopes: string[]) => void;
+
+  constructor(dependencies: InventoryServiceDependencies) {
+    this.api = dependencies.api;
+    this.logger = dependencies.logger.child({ component: 'InventoryService' });
+    this.userId = dependencies.userId;
+    this.ensureScopes = dependencies.scopeChecker;
+  }
+
+  createBuilder(): InventoryUpdateBuilder {
+    return new InventoryUpdateBuilder();
+  }
+
+  async update(
+    builderOrCallback: InventoryUpdateBuilder | ((builder: InventoryUpdateBuilder) => void | Promise<void>),
+    options: InventoryBuilderOptions = {},
+  ): Promise<void> {
+    const builder = builderOrCallback instanceof InventoryUpdateBuilder ? builderOrCallback : this.createBuilder();
+    if (!(builderOrCallback instanceof InventoryUpdateBuilder)) {
+      await builderOrCallback(builder);
+    }
+
+    if (builder.isEmpty()) {
+      this.logger.debug('Inventory update skipped because builder produced no changes.');
+      return;
+    }
+
+    this.ensureScopes(['server']);
+    const payload = builder.toRequest(options);
+    await this.invokeInventoryPut(payload);
+  }
+
+  async setCurrencies(currencyValues: Record<string, bigint | number>, transaction?: string): Promise<void> {
+    this.ensureScopes(['server']);
+    const current = await this.getCurrencies(Object.keys(currencyValues));
+    const deltas: Record<string, bigint> = {};
+    for (const [currencyId, target] of Object.entries(currencyValues)) {
+      const currentVal = current[currencyId] ?? BigInt(0);
+      const targetValue = BigInt(target);
+      const delta = targetValue - currentVal;
+      if (delta !== BigInt(0)) {
+        deltas[currencyId] = delta;
+      }
+    }
+
+    if (Object.keys(deltas).length === 0) {
+      this.logger.debug('No currency adjustments required; request skipped.');
+      return;
+    }
+
+    await this.update((builder) => {
+      for (const [currencyId, delta] of Object.entries(deltas)) {
+        builder.currencyChange(currencyId, delta);
+      }
+    }, { transaction });
+  }
+
+  async addCurrencies(currencyDeltas: Record<string, bigint | number>, transaction?: string): Promise<void> {
+    await this.update((builder) => {
+      for (const [currencyId, delta] of Object.entries(currencyDeltas)) {
+        builder.currencyChange(currencyId, delta);
+      }
+    }, { transaction });
+  }
+
+  async addItem(contentId: string, properties: Record<string, string> = {}, transaction?: string): Promise<void> {
+    await this.update((builder) => {
+      builder.addItem(contentId, properties);
+    }, { transaction });
+  }
+
+  async deleteItem(contentId: string, itemId: bigint | number | string, transaction?: string): Promise<void> {
+    await this.update((builder) => {
+      builder.deleteItem(contentId, itemId);
+    }, { transaction });
+  }
+
+  async updateItem(
+    contentId: string,
+    itemId: bigint | number | string,
+    properties: Record<string, string>,
+    transaction?: string,
+  ): Promise<void> {
+    await this.update((builder) => {
+      builder.updateItem(contentId, itemId, properties);
+    }, { transaction });
+  }
+
+  async setCurrencyProperties(
+    currencyId: string,
+    properties: CurrencyProperty[],
+    transaction?: string,
+  ): Promise<void> {
+    await this.update((builder) => {
+      builder.setCurrencyProperties(currencyId, properties);
+    }, { transaction });
+  }
+
+  async previewCurrencyGain(currencyChanges: Record<string, bigint | number>): Promise<PreviewVipBonusResponse> {
+    this.ensureScopes(['server']);
+    const payload: InventoryUpdatePayload = {
+      currencies: Object.fromEntries(
+        Object.entries(currencyChanges).map(([currencyId, amount]) => [currencyId, BigInt(amount).toString()]),
+      ),
+    };
+    const response = await this.invokePreview(payload);
+    return response;
+  }
+
+  async getMultipliers(): Promise<MultipliersGetResponse> {
+    this.ensureScopes(['server']);
+    const response = await this.invokeGetMultipliers();
+    return response;
+  }
+
+  async getInventory(scope?: string): Promise<InventoryView> {
+    this.ensureScopes(['server']);
+    const response = await this.invokeGetInventory(scope);
+    return response;
+  }
+
+  async getCurrencies(currencyIds?: string[]): Promise<Record<string, bigint>> {
+    const scope = Array.isArray(currencyIds) && currencyIds.length > 0 ? currencyIds.join(',') : 'currency';
+    const view = await this.getInventory(scope);
+    const result: Record<string, bigint> = {};
+    for (const currency of view.currencies ?? []) {
+      result[currency.id] = BigInt(currency.amount);
+    }
+    return result;
+  }
+
+  async sendCurrency(
+    request: Omit<TransferRequestPayload, 'recipientPlayer'> & { recipientPlayer: string | number },
+  ): Promise<void> {
+    this.ensureScopes(['server']);
+    const payload: TransferRequestPayload = {
+      recipientPlayer: this.toIdentifier(request.recipientPlayer),
+      currencies: Object.fromEntries(
+        Object.entries(request.currencies ?? {}).map(([currencyId, amount]) => [currencyId, BigInt(amount).toString()]),
+      ),
+      transaction: request.transaction,
+    };
+    const response = this.api.inventoryPutTransferByObjectId?.(this.userId, payload);
+    if (!response || typeof (response as Promise<unknown>).then !== 'function') {
+      throw new Error('inventoryPutTransferByObjectId API is unavailable in the current SDK.');
+    }
+    await response;
+  }
+
+  private async invokeInventoryPut(payload: InventoryUpdatePayload): Promise<void> {
+    const response = this.api.inventoryPutByObjectId?.(this.userId, payload);
+    if (!response || typeof (response as Promise<unknown>).then !== 'function') {
+      throw new Error('inventoryPutByObjectId API is unavailable in the current SDK.');
+    }
+    await response;
+  }
+
+  private async invokePreview(payload: InventoryUpdatePayload): Promise<PreviewVipBonusResponse> {
+    const response = this.api.inventoryPutPreviewByObjectId?.(this.userId, payload);
+    if (!response || typeof (response as Promise<unknown>).then !== 'function') {
+      throw new Error('inventoryPutPreviewByObjectId API is unavailable in the current SDK.');
+    }
+    const result = await response;
+    if (!result || typeof result !== 'object' || !('body' in result)) {
+      return result as PreviewVipBonusResponse;
+    }
+    return (result as { body: PreviewVipBonusResponse }).body;
+  }
+
+  private async invokeGetMultipliers(): Promise<MultipliersGetResponse> {
+    const response = this.api.inventoryGetMultipliersByObjectId?.(this.userId);
+    if (!response || typeof (response as Promise<unknown>).then !== 'function') {
+      throw new Error('inventoryGetMultipliersByObjectId API is unavailable in the current SDK.');
+    }
+    const result = await response;
+    if (!result || typeof result !== 'object' || !('body' in result)) {
+      return result as MultipliersGetResponse;
+    }
+    return (result as { body: MultipliersGetResponse }).body;
+  }
+
+  private async invokeGetInventory(scope?: string): Promise<InventoryView> {
+    const response = this.api.inventoryGetByObjectId?.(this.userId, scope);
+    if (!response || typeof (response as Promise<unknown>).then !== 'function') {
+      throw new Error('inventoryGetByObjectId API is unavailable in the current SDK.');
+    }
+    const result = await response;
+    if (!result || typeof result !== 'object' || !('body' in result)) {
+      return result as InventoryView;
+    }
+    return (result as { body: InventoryView }).body;
+  }
+
+  private toIdentifier(value: string | number | bigint): string {
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (!trimmed) {
+        throw new Error('Identifier cannot be empty.');
+      }
+      return trimmed;
+    }
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) {
+        throw new Error(`Invalid numeric identifier: ${value}`);
+      }
+      return Math.trunc(value).toString();
+    }
+    return value.toString();
+  }
+}
+
+export function createInventoryService(
+  api: BoundBeamApi,
+  logger: Logger,
+  userId: string,
+  hasScopes: (scopes: string[]) => boolean,
+): InventoryService {
+  return new InventoryService({
+    api,
+    logger,
+    userId,
+    scopeChecker: (requiredScopes: string[]) => {
+      if (!hasScopes(requiredScopes)) {
+        throw new MissingScopesError(requiredScopes);
+      }
+    },
+  });
+}
+

package/src/logger.ts

@@ -0,0 +1,38 @@
+import pino, { destination, type Logger, type LoggerOptions } from 'pino';
+import { ensureWritableTempDirectory } from './env.js';
+import type { EnvironmentConfig } from './types.js';
+
+interface LoggerFactoryOptions {
+  name?: string;
+  destinationPath?: string;
+}
+
+export function createLogger(env: EnvironmentConfig, options: LoggerFactoryOptions = {}): Logger {
+  const configuredDestination = options.destinationPath ?? process.env.LOG_PATH;
+
+  const pinoOptions: LoggerOptions = {
+    name: options.name ?? 'beamable-node-runtime',
+    level: env.logLevel,
+    base: {
+      cid: env.cid,
+      pid: env.pid,
+      routingKey: env.routingKey ?? null,
+      sdkVersionExecution: env.sdkVersionExecution,
+    },
+    redact: {
+      paths: ['secret', 'refreshToken'],
+      censor: '***',
+    },
+  };
+
+  // For deployed services, always log to stdout so container orchestrator can collect logs
+  // For local development, log to stdout unless a specific file path is provided
+  if (!configuredDestination || configuredDestination === '-' || configuredDestination === 'stdout' || configuredDestination === 'console') {
+    // Log to stdout (default pino behavior) - this is critical for container log collection
+    return pino(pinoOptions, process.stdout);
+  }
+
+  const resolvedDestination = configuredDestination === 'temp' ? ensureWritableTempDirectory() : configuredDestination;
+  const stream = destination({ dest: resolvedDestination, mkdir: true, append: true, sync: false });
+  return pino(pinoOptions, stream);
+}

package/src/message.ts

@@ -0,0 +1,19 @@
+import type { GatewayRequest, GatewayResponse, WebsocketEventEnvelope } from './types.js';
+
+let nextRequestId = -1;
+
+export function allocateRequestId(): number {
+  nextRequestId -= 1;
+  if (nextRequestId < -9_000_000_000) {
+    nextRequestId = -1;
+  }
+  return nextRequestId;
+}
+
+export function serializeGatewayRequest(request: GatewayRequest): string {
+  return JSON.stringify(request);
+}
+
+export function deserializeGatewayResponse(raw: string): GatewayResponse | WebsocketEventEnvelope {
+  return JSON.parse(raw) as GatewayResponse | WebsocketEventEnvelope;
+}

package/src/requester.ts

@@ -0,0 +1,126 @@
+import { EventEmitter } from 'node:events';
+import type { Logger } from 'pino';
+import { AuthenticationError, TimeoutError } from './errors.js';
+import { allocateRequestId, deserializeGatewayResponse, serializeGatewayRequest } from './message.js';
+import { BeamableWebSocket } from './websocket.js';
+import type { GatewayRequest, GatewayResponse, WebsocketEventEnvelope } from './types.js';
+
+interface PendingRequest<T = unknown> {
+  resolve: (value: T) => void;
+  reject: (error: Error) => void;
+  timeoutHandle: NodeJS.Timeout;
+  path: string;
+  method: string;
+}
+
+export class GatewayRequester {
+  private readonly socket: BeamableWebSocket;
+  private readonly logger: Logger;
+  private readonly pending = new Map<number, PendingRequest>();
+  private readonly emitter = new EventEmitter();
+  private requestTimeoutMs = 15_000;
+
+  constructor(socket: BeamableWebSocket, logger: Logger) {
+    this.socket = socket;
+    this.logger = logger.child({ component: 'GatewayRequester' });
+    this.socket.on('message', (...args) => this.onRawMessage(String(args[0] ?? '')));
+  }
+
+  on(event: 'event', listener: (envelope: WebsocketEventEnvelope) => void): void {
+    this.emitter.on(event, listener);
+  }
+
+  off(event: 'event', listener: (envelope: WebsocketEventEnvelope) => void): void {
+    this.emitter.off(event, listener);
+  }
+
+  setRequestTimeout(timeoutMs: number): void {
+    this.requestTimeoutMs = timeoutMs;
+  }
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const id = allocateRequestId();
+    const effectiveBody = body ?? {};
+    const request: GatewayRequest = {
+      id,
+      method: method.toLowerCase(),
+      path,
+      body: effectiveBody,
+    };
+
+    this.logger.debug({ id, method, path, body: effectiveBody }, 'Sending gateway request.');
+
+    const payload = serializeGatewayRequest(request);
+
+    return new Promise<T>((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new TimeoutError(`Request ${method} ${path} timed out after ${this.requestTimeoutMs}ms`));
+      }, this.requestTimeoutMs).unref();
+
+      this.pending.set(id, {
+        resolve: resolve as (value: unknown) => void,
+        reject,
+        timeoutHandle,
+        path,
+        method,
+      });
+
+      this.socket
+        .send(payload)
+        .catch((error) => {
+          clearTimeout(timeoutHandle);
+          this.pending.delete(id);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+  }
+
+  async sendResponse(response: GatewayResponse): Promise<void> {
+    const payload = JSON.stringify(response);
+    await this.socket.send(payload);
+  }
+
+  async acknowledge(id: number, status = 200): Promise<void> {
+    await this.sendResponse({ id, status, body: null });
+  }
+
+  private onRawMessage(raw: string): void {
+    this.logger.debug({ raw }, 'Received websocket frame.');
+    let envelope: GatewayResponse | WebsocketEventEnvelope;
+    try {
+      envelope = deserializeGatewayResponse(raw);
+    } catch (error) {
+      this.logger.error({ err: error, raw }, 'Failed to parse gateway message.');
+      return;
+    }
+
+    if (typeof envelope.id !== 'number') {
+      this.logger.warn({ envelope }, 'Invalid gateway message without id.');
+      return;
+    }
+
+    const pending = this.pending.get(envelope.id);
+    if (pending) {
+      clearTimeout(pending.timeoutHandle);
+      this.pending.delete(envelope.id);
+      if ('status' in envelope && envelope.status === 403) {
+        pending.reject(new AuthenticationError('Gateway rejected the request with 403.'));
+        return;
+      }
+      pending.resolve(envelope.body as unknown);
+      return;
+    }
+
+    this.emitter.emit('event', envelope as WebsocketEventEnvelope);
+  }
+
+  dispose(): void {
+    for (const [id, pending] of this.pending.entries()) {
+      clearTimeout(pending.timeoutHandle);
+      pending.reject(new Error(`Request ${pending.method} ${pending.path} cancelled during shutdown.`));
+      this.pending.delete(id);
+    }
+    this.emitter.removeAllListeners();
+  }
+}