@faynosync/sdk-js 0.1.0

package/examples/custom-fetch/index.ts

@@ -0,0 +1,94 @@
+import https from 'https';
+import { Client, RequestFailedError } from '../../src';
+import type { UpdateResponse, UpdateSource } from '../../src';
+
+const DEVICE_ID = 'device-1';
+
+const keepAliveAgent = new https.Agent({
+  keepAlive: true,
+  maxSockets: 10,
+  timeout: 5_000,
+});
+
+const customFetch: typeof globalThis.fetch = (input, init) => {
+  return globalThis.fetch(input, {
+    ...init,
+    agent: keepAliveAgent,
+  });
+};
+
+const client = new Client({
+  baseURL: 'http://localhost:9000',
+  fetch: customFetch,
+  timeoutMs: 10_000,
+});
+
+async function main(): Promise<void> {
+  let resp: UpdateResponse;
+  try {
+    resp = await client.checkForUpdates({
+      owner: 'admin',
+      appName: 'test',
+      version: '0.0.0.1',
+      channel: 'nightly',
+      platform: 'darwin',
+      arch: 'arm64',
+      deviceId: DEVICE_ID,
+    });
+  } catch (err) {
+    if (err instanceof RequestFailedError) {
+      console.error('update check request failed:', err.message);
+    } else {
+      console.error('invalid update check options:', (err as Error).message);
+    }
+    process.exit(1);
+  }
+
+  printUpdateResponse(resp);
+}
+
+function printUpdateResponse(resp: UpdateResponse): void {
+  const pad = '  ';
+
+  console.log('-- Update check response --');
+  console.log(`${pad}update_available:         ${resp.updateAvailable}`);
+  console.log(`${pad}critical:                 ${resp.critical}`);
+  console.log(`${pad}is_intermediate_required: ${resp.isIntermediateRequired}`);
+  console.log(`${pad}possible_rollback:        ${resp.possibleRollback}`);
+  console.log(`${pad}source:                   ${formatUpdateSource(resp.source)}`);
+
+  if (resp.updateUrl !== '') {
+    console.log(`${pad}update_url:               ${resp.updateUrl}`);
+  } else {
+    console.log(`${pad}update_url:               (empty)`);
+  }
+
+  if (resp.changelog !== '') {
+    console.log(`${pad}changelog:`);
+    for (const line of resp.changelog.trimEnd().split('\n')) {
+      console.log(`${pad}  ${line}`);
+    }
+  } else {
+    console.log(`${pad}changelog:               (empty)`);
+  }
+
+  if (resp.packageUrls.length === 0) {
+    console.log(`${pad}package_urls:           (none)`);
+    return;
+  }
+
+  console.log(`${pad}package_urls:`);
+  for (const pkg of resp.packageUrls) {
+    console.log(`${pad}  ${pkg.package.padEnd(12)} ${pkg.url}`);
+  }
+}
+
+function formatUpdateSource(source: UpdateSource): string {
+  switch (source) {
+    case 'edge': return 'edge';
+    case 'api':  return 'api';
+    default:     return 'unknown';
+  }
+}
+
+main();

package/examples/edge-fallback/README.md

@@ -0,0 +1,24 @@
+# edge-fallback
+
+Update check with a static edge CDN configured alongside the base API.
+
+Demonstrates:
+
+- Configuring `edgeURL` for a static JSON edge response
+- Automatic fallback to `baseURL` when the edge misses or fails
+- Passing `deviceId` to trigger a telemetry beacon after a successful edge hit
+- Reading `resp.source` to see which endpoint served the response
+
+## How it works
+
+1. The SDK requests `GET {edgeURL}/responses/{owner}/{appName}/{channel}/{platform}/{arch}/{version}.json`.
+2. On HTTP 200 with valid JSON, the response is returned with `source: 'edge'` and a telemetry beacon is sent to `{baseURL}/telemetry/beacon`.
+3. On any failure (404, network error, invalid JSON), the SDK retries against `{baseURL}/checkVersion`.
+
+## Run
+
+```sh
+npx ts-node examples/edge-fallback/index.ts
+```
+
+Expects a faynoSync server at `http://localhost:9000` and an edge server at `http://cb-faynosync-s3-public.web.garage.localhost:3902`.

package/examples/edge-fallback/index.ts

@@ -0,0 +1,77 @@
+import { Client, RequestFailedError } from '../../src';
+import type { UpdateResponse, UpdateSource } from '../../src';
+
+const client = new Client({
+  baseURL: 'http://localhost:9000',
+  edgeURL: 'http://cb-faynosync-s3-public.web.garage.localhost:3902',
+});
+
+async function main(): Promise<void> {
+  let resp: UpdateResponse;
+  try {
+    resp = await client.checkForUpdates({
+      owner: 'admin',
+      appName: 'test',
+      version: '0.0.0.1',
+      channel: 'nightly',
+      platform: 'darwin',
+      arch: 'arm64',
+      deviceId: 'device-1-fnsj',
+    });
+  } catch (err) {
+    if (err instanceof RequestFailedError) {
+      console.error('update check request failed:', err.message);
+    } else {
+      console.error('invalid update check options:', (err as Error).message);
+    }
+    process.exit(1);
+  }
+
+  printUpdateResponse(resp);
+}
+
+function printUpdateResponse(resp: UpdateResponse): void {
+  const pad = '  ';
+
+  console.log('-- Update check response --');
+  console.log(`${pad}update_available:         ${resp.updateAvailable}`);
+  console.log(`${pad}critical:                 ${resp.critical}`);
+  console.log(`${pad}is_intermediate_required: ${resp.isIntermediateRequired}`);
+  console.log(`${pad}possible_rollback:        ${resp.possibleRollback}`);
+  console.log(`${pad}source:                   ${formatUpdateSource(resp.source)}`);
+
+  if (resp.updateUrl !== '') {
+    console.log(`${pad}update_url:               ${resp.updateUrl}`);
+  } else {
+    console.log(`${pad}update_url:               (empty)`);
+  }
+
+  if (resp.changelog !== '') {
+    console.log(`${pad}changelog:`);
+    for (const line of resp.changelog.trimEnd().split('\n')) {
+      console.log(`${pad}  ${line}`);
+    }
+  } else {
+    console.log(`${pad}changelog:               (empty)`);
+  }
+
+  if (resp.packageUrls.length === 0) {
+    console.log(`${pad}package_urls:           (none)`);
+    return;
+  }
+
+  console.log(`${pad}package_urls:`);
+  for (const pkg of resp.packageUrls) {
+    console.log(`${pad}  ${pkg.package.padEnd(12)} ${pkg.url}`);
+  }
+}
+
+function formatUpdateSource(source: UpdateSource): string {
+  switch (source) {
+    case 'edge': return 'edge';
+    case 'api':  return 'api';
+    default:     return 'unknown';
+  }
+}
+
+main();

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/tests/**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.test.json' }],
+  },
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@faynosync/sdk-js",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for faynoSync",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "tsc --project tsconfig.test.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,264 @@
+import type { CheckOptions, PackageUpdateURL, UpdateResponse, UpdateSource } from './types';
+import {
+  CheckError,
+  EndpointError,
+  ErrInvalidBaseURL,
+  ErrInvalidEdgeURL,
+  ErrMissingAppName,
+  ErrMissingBaseURL,
+  ErrMissingOwner,
+  ErrMissingVersion,
+  ValidationError,
+} from './errors';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const USER_AGENT = 'faynosync-js/1.0';
+
+export interface Config {
+  readonly baseURL: string;
+  readonly edgeURL?: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly timeoutMs?: number;
+}
+
+interface RawUpdateResponse {
+  update_available?: boolean;
+  update_url?: string;
+  changelog?: string;
+  critical?: boolean;
+  is_intermediate_required?: boolean;
+  possible_rollback?: boolean;
+  [key: string]: unknown;
+}
+
+export class Client {
+  private readonly baseURL: string;
+  private readonly edgeURL: string;
+  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly timeoutMs: number;
+
+  constructor(cfg: Config) {
+    this.baseURL = cfg.baseURL;
+    this.edgeURL = cfg.edgeURL ?? '';
+    this.fetchFn = cfg.fetch ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async checkForUpdates(opts: CheckOptions, signal?: AbortSignal): Promise<UpdateResponse> {
+    this.validateConfig();
+    validateCheckOptions(opts);
+
+    const sig = signal ?? null;
+    let edgeError: Error | undefined;
+
+    if (this.edgeURL !== '') {
+      try {
+        const resp = await this.checkEdge(opts, sig);
+        if (opts.deviceId) {
+          try {
+            await this.sendEdgeTelemetryBeacon(opts, !resp.updateAvailable, sig);
+          } catch {
+            // telemetry failures don't affect the update check result
+          }
+        }
+        return { ...resp, source: 'edge' };
+      } catch (err) {
+        edgeError = err as Error;
+        if (signal?.aborted === true) {
+          throw new CheckError(edgeError);
+        }
+      }
+    }
+
+    try {
+      const resp = await this.checkAPI(opts, sig);
+      return { ...resp, source: 'api' };
+    } catch (apiError) {
+      throw new CheckError(edgeError, apiError as Error);
+    }
+  }
+
+  private validateConfig(): void {
+    if (this.baseURL.trim() === '') {
+      throw ErrMissingBaseURL;
+    }
+    parseAbsoluteURL(this.baseURL, ErrInvalidBaseURL);
+  }
+
+  private async checkEdge(opts: CheckOptions, signal: AbortSignal | null): Promise<UpdateResponse> {
+    const url = this.buildEdgeCheckURL(opts);
+    return this.doUpdateRequest(url, opts.deviceId, 'edge', signal);
+  }
+
+  private async checkAPI(opts: CheckOptions, signal: AbortSignal | null): Promise<UpdateResponse> {
+    const url = this.buildAPICheckURL(opts);
+    return this.doUpdateRequest(url, opts.deviceId, 'api', signal);
+  }
+
+  private async doUpdateRequest(
+    url: string,
+    deviceId: string | undefined,
+    source: UpdateSource,
+    signal: AbortSignal | null,
+  ): Promise<UpdateResponse> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'User-Agent': USER_AGENT,
+    };
+    if (deviceId) {
+      headers['X-Device-ID'] = deviceId;
+    }
+
+    const reqSignal = createRequestSignal(signal, this.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await this.fetchFn(url, { headers, signal: reqSignal });
+    } catch (err) {
+      throw new EndpointError(source, url, undefined, err as Error);
+    }
+
+    if (res.status !== 200) {
+      await res.body?.cancel();
+      throw new EndpointError(source, url, res.status);
+    }
+
+    let raw: RawUpdateResponse;
+    try {
+      raw = (await res.json()) as RawUpdateResponse;
+    } catch (err) {
+      throw new EndpointError(source, url, undefined, err as Error);
+    }
+
+    return parseUpdateResponse(raw);
+  }
+
+  private buildAPICheckURL(opts: CheckOptions): string {
+    const u = parseAbsoluteURL(this.baseURL, ErrInvalidBaseURL);
+    u.pathname = joinURLPath(u.pathname, 'checkVersion');
+    u.search = new URLSearchParams({
+      app_name: opts.appName,
+      version: opts.version,
+      channel: opts.channel ?? '',
+      platform: opts.platform ?? '',
+      arch: opts.arch ?? '',
+      owner: opts.owner,
+    }).toString();
+    return u.toString();
+  }
+
+  private buildEdgeCheckURL(opts: CheckOptions): string {
+    const u = parseAbsoluteURL(this.edgeURL, ErrInvalidEdgeURL);
+    const segments = [
+      'responses',
+      opts.owner,
+      opts.appName,
+      opts.channel ?? '',
+      opts.platform ?? '',
+      opts.arch ?? '',
+      `${opts.version}.json`,
+    ];
+    const base = (u.origin + u.pathname).replace(/\/+$/, '');
+    return `${base}/${segments.map(encodeURIComponent).join('/')}`;
+  }
+
+  private buildEdgeTelemetryBeaconURL(opts: CheckOptions, isLatest: boolean): string {
+    const u = parseAbsoluteURL(this.baseURL, ErrInvalidBaseURL);
+    u.pathname = joinURLPath(u.pathname, 'telemetry/beacon');
+    u.search = new URLSearchParams({
+      app_name: opts.appName,
+      version: opts.version,
+      channel: opts.channel ?? '',
+      platform: opts.platform ?? '',
+      arch: opts.arch ?? '',
+      owner: opts.owner,
+      is_latest: String(isLatest),
+    }).toString();
+    return u.toString();
+  }
+
+  private async sendEdgeTelemetryBeacon(
+    opts: CheckOptions,
+    isLatest: boolean,
+    signal: AbortSignal | null,
+  ): Promise<void> {
+    const url = this.buildEdgeTelemetryBeaconURL(opts, isLatest);
+    const headers: Record<string, string> = { 'User-Agent': USER_AGENT };
+    if (opts.deviceId) {
+      headers['X-Device-ID'] = opts.deviceId;
+    }
+
+    const reqSignal = createRequestSignal(signal, this.timeoutMs);
+    const res = await this.fetchFn(url, { headers, signal: reqSignal });
+    await res.body?.cancel();
+    if (res.status !== 200) {
+      throw new EndpointError('edge', url, res.status);
+    }
+  }
+}
+
+function validateCheckOptions(opts: CheckOptions): void {
+  if (!opts.owner) throw ErrMissingOwner;
+  if (!opts.appName) throw ErrMissingAppName;
+  if (!opts.version) throw ErrMissingVersion;
+}
+
+function parseAbsoluteURL(raw: string, sentinel: ValidationError): URL {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw sentinel;
+  }
+  if (!u.protocol || !u.hostname) {
+    throw sentinel;
+  }
+  return u;
+}
+
+function joinURLPath(basePath: string, segment: string): string {
+  if (basePath === '' || basePath === '/') {
+    return `/${segment}`;
+  }
+  return `${basePath.replace(/\/+$/, '')}/${segment}`;
+}
+
+function createRequestSignal(userSignal: AbortSignal | null, timeoutMs: number): AbortSignal {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  if (userSignal === null) return timeoutSignal;
+
+  if (userSignal.aborted) {
+    const c = new AbortController();
+    c.abort(userSignal.reason);
+    return c.signal;
+  }
+
+  const controller = new AbortController();
+  const abort = (reason: unknown) => controller.abort(reason);
+  userSignal.addEventListener('abort', () => abort(userSignal.reason), { once: true });
+  timeoutSignal.addEventListener('abort', () => abort(timeoutSignal.reason), { once: true });
+  return controller.signal;
+}
+
+function parseUpdateResponse(raw: RawUpdateResponse): UpdateResponse {
+  const packageUrls: PackageUpdateURL[] = [];
+
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.startsWith('update_url_') && typeof value === 'string') {
+      packageUrls.push({ package: key.slice('update_url_'.length), url: value });
+    }
+  }
+
+  packageUrls.sort((a, b) => a.package.localeCompare(b.package));
+
+  return {
+    updateAvailable: raw.update_available ?? false,
+    updateUrl: raw.update_url ?? '',
+    changelog: raw.changelog ?? '',
+    critical: raw.critical ?? false,
+    isIntermediateRequired: raw.is_intermediate_required ?? false,
+    possibleRollback: raw.possible_rollback ?? false,
+    packageUrls,
+    source: 'unknown',
+  };
+}

package/src/errors.ts

@@ -0,0 +1,72 @@
+import type { UpdateSource } from './types';
+
+export class FaynoSyncError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FaynoSyncError';
+  }
+}
+
+export class ValidationError extends FaynoSyncError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+export class RequestFailedError extends FaynoSyncError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RequestFailedError';
+  }
+}
+
+export class EndpointError extends RequestFailedError {
+  constructor(
+    public readonly source: UpdateSource,
+    public readonly endpointUrl: string,
+    public readonly statusCode?: number,
+    cause?: Error,
+  ) {
+    let msg: string;
+    if (statusCode !== undefined) {
+      msg = `faynosync: request failed: ${endpointUrl} returned HTTP ${statusCode}`;
+    } else if (cause !== undefined) {
+      msg = `faynosync: request failed: ${endpointUrl}: ${cause.message}`;
+    } else {
+      msg = `faynosync: request failed: ${endpointUrl}`;
+    }
+    super(msg);
+    this.name = 'EndpointError';
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+export class CheckError extends RequestFailedError {
+  constructor(
+    public readonly edgeError?: Error,
+    public readonly apiError?: Error,
+  ) {
+    let msg: string;
+    if (edgeError !== undefined && apiError !== undefined) {
+      msg = `faynosync: request failed: edge failed: ${edgeError.message}; api failed: ${apiError.message}`;
+    } else if (edgeError !== undefined) {
+      msg = `faynosync: request failed: edge failed: ${edgeError.message}`;
+    } else if (apiError !== undefined) {
+      msg = `faynosync: request failed: api failed: ${apiError.message}`;
+    } else {
+      msg = 'faynosync: request failed';
+    }
+    super(msg);
+    this.name = 'CheckError';
+  }
+}
+
+export const ErrMissingBaseURL = new ValidationError('faynosync: missing base URL');
+export const ErrInvalidBaseURL = new ValidationError('faynosync: invalid base URL');
+export const ErrInvalidEdgeURL = new ValidationError('faynosync: invalid edge URL');
+export const ErrMissingOwner = new ValidationError('faynosync: missing owner');
+export const ErrMissingAppName = new ValidationError('faynosync: missing app name');
+export const ErrMissingVersion = new ValidationError('faynosync: missing version');

package/src/index.ts

@@ -0,0 +1,17 @@
+export { Client } from './client';
+export type { Config } from './client';
+export type { CheckOptions, PackageUpdateURL, UpdateResponse, UpdateSource } from './types';
+export {
+  CheckError,
+  EndpointError,
+  ErrInvalidBaseURL,
+  ErrInvalidEdgeURL,
+  ErrMissingAppName,
+  ErrMissingBaseURL,
+  ErrMissingOwner,
+  ErrMissingVersion,
+  FaynoSyncError,
+  RequestFailedError,
+  ValidationError,
+} from './errors';
+export { systemArch, systemPlatform } from './system';

package/src/system.ts

@@ -0,0 +1,7 @@
+export function systemPlatform(): string {
+  return process.platform;
+}
+
+export function systemArch(): string {
+  return process.arch;
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+export type UpdateSource = 'unknown' | 'edge' | 'api';
+
+export interface PackageUpdateURL {
+  readonly package: string;
+  readonly url: string;
+}
+
+export interface CheckOptions {
+  readonly owner: string;
+  readonly appName: string;
+  readonly version: string;
+  readonly channel?: string;
+  readonly platform?: string;
+  readonly arch?: string;
+  readonly deviceId?: string;
+}
+
+export interface UpdateResponse {
+  readonly updateAvailable: boolean;
+  readonly updateUrl: string;
+  readonly changelog: string;
+  readonly critical: boolean;
+  readonly isIntermediateRequired: boolean;
+  readonly possibleRollback: boolean;
+  readonly packageUrls: readonly PackageUpdateURL[];
+  readonly source: UpdateSource;
+}