@faynosync/sdk-js 0.1.0

package/dist/client.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_TIMEOUT_MS = 30_000;
+const USER_AGENT = 'faynosync-js/1.0';
+class Client {
+    baseURL;
+    edgeURL;
+    fetchFn;
+    timeoutMs;
+    constructor(cfg) {
+        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, signal) {
+        this.validateConfig();
+        validateCheckOptions(opts);
+        const sig = signal ?? null;
+        let edgeError;
+        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;
+                if (signal?.aborted === true) {
+                    throw new errors_1.CheckError(edgeError);
+                }
+            }
+        }
+        try {
+            const resp = await this.checkAPI(opts, sig);
+            return { ...resp, source: 'api' };
+        }
+        catch (apiError) {
+            throw new errors_1.CheckError(edgeError, apiError);
+        }
+    }
+    validateConfig() {
+        if (this.baseURL.trim() === '') {
+            throw errors_1.ErrMissingBaseURL;
+        }
+        parseAbsoluteURL(this.baseURL, errors_1.ErrInvalidBaseURL);
+    }
+    async checkEdge(opts, signal) {
+        const url = this.buildEdgeCheckURL(opts);
+        return this.doUpdateRequest(url, opts.deviceId, 'edge', signal);
+    }
+    async checkAPI(opts, signal) {
+        const url = this.buildAPICheckURL(opts);
+        return this.doUpdateRequest(url, opts.deviceId, 'api', signal);
+    }
+    async doUpdateRequest(url, deviceId, source, signal) {
+        const headers = {
+            Accept: 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        if (deviceId) {
+            headers['X-Device-ID'] = deviceId;
+        }
+        const reqSignal = createRequestSignal(signal, this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchFn(url, { headers, signal: reqSignal });
+        }
+        catch (err) {
+            throw new errors_1.EndpointError(source, url, undefined, err);
+        }
+        if (res.status !== 200) {
+            await res.body?.cancel();
+            throw new errors_1.EndpointError(source, url, res.status);
+        }
+        let raw;
+        try {
+            raw = (await res.json());
+        }
+        catch (err) {
+            throw new errors_1.EndpointError(source, url, undefined, err);
+        }
+        return parseUpdateResponse(raw);
+    }
+    buildAPICheckURL(opts) {
+        const u = parseAbsoluteURL(this.baseURL, errors_1.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();
+    }
+    buildEdgeCheckURL(opts) {
+        const u = parseAbsoluteURL(this.edgeURL, errors_1.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('/')}`;
+    }
+    buildEdgeTelemetryBeaconURL(opts, isLatest) {
+        const u = parseAbsoluteURL(this.baseURL, errors_1.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();
+    }
+    async sendEdgeTelemetryBeacon(opts, isLatest, signal) {
+        const url = this.buildEdgeTelemetryBeaconURL(opts, isLatest);
+        const headers = { '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 errors_1.EndpointError('edge', url, res.status);
+        }
+    }
+}
+exports.Client = Client;
+function validateCheckOptions(opts) {
+    if (!opts.owner)
+        throw errors_1.ErrMissingOwner;
+    if (!opts.appName)
+        throw errors_1.ErrMissingAppName;
+    if (!opts.version)
+        throw errors_1.ErrMissingVersion;
+}
+function parseAbsoluteURL(raw, sentinel) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw sentinel;
+    }
+    if (!u.protocol || !u.hostname) {
+        throw sentinel;
+    }
+    return u;
+}
+function joinURLPath(basePath, segment) {
+    if (basePath === '' || basePath === '/') {
+        return `/${segment}`;
+    }
+    return `${basePath.replace(/\/+$/, '')}/${segment}`;
+}
+function createRequestSignal(userSignal, timeoutMs) {
+    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) => 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) {
+    const packageUrls = [];
+    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',
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import type { UpdateSource } from './types';
+export declare class FaynoSyncError extends Error {
+    constructor(message: string);
+}
+export declare class ValidationError extends FaynoSyncError {
+    constructor(message: string);
+}
+export declare class RequestFailedError extends FaynoSyncError {
+    constructor(message: string);
+}
+export declare class EndpointError extends RequestFailedError {
+    readonly source: UpdateSource;
+    readonly endpointUrl: string;
+    readonly statusCode?: number | undefined;
+    constructor(source: UpdateSource, endpointUrl: string, statusCode?: number | undefined, cause?: Error);
+}
+export declare class CheckError extends RequestFailedError {
+    readonly edgeError?: Error | undefined;
+    readonly apiError?: Error | undefined;
+    constructor(edgeError?: Error | undefined, apiError?: Error | undefined);
+}
+export declare const ErrMissingBaseURL: ValidationError;
+export declare const ErrInvalidBaseURL: ValidationError;
+export declare const ErrInvalidEdgeURL: ValidationError;
+export declare const ErrMissingOwner: ValidationError;
+export declare const ErrMissingAppName: ValidationError;
+export declare const ErrMissingVersion: ValidationError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,aAAc,SAAQ,kBAAkB;aAEjC,MAAM,EAAE,YAAY;aACpB,WAAW,EAAE,MAAM;aACnB,UAAU,CAAC,EAAE,MAAM;gBAFnB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,KAAK,CAAC,EAAE,KAAK;CAgBhB;AAED,qBAAa,UAAW,SAAQ,kBAAkB;aAE9B,SAAS,CAAC,EAAE,KAAK;aACjB,QAAQ,CAAC,EAAE,KAAK;gBADhB,SAAS,CAAC,EAAE,KAAK,YAAA,EACjB,QAAQ,CAAC,EAAE,KAAK,YAAA;CAenC;AAED,eAAO,MAAM,iBAAiB,iBAAqD,CAAC;AACpF,eAAO,MAAM,iBAAiB,iBAAqD,CAAC;AACpF,eAAO,MAAM,iBAAiB,iBAAqD,CAAC;AACpF,eAAO,MAAM,eAAe,iBAAkD,CAAC;AAC/E,eAAO,MAAM,iBAAiB,iBAAqD,CAAC;AACpF,eAAO,MAAM,iBAAiB,iBAAoD,CAAC"}

package/dist/errors.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrMissingVersion = exports.ErrMissingAppName = exports.ErrMissingOwner = exports.ErrInvalidEdgeURL = exports.ErrInvalidBaseURL = exports.ErrMissingBaseURL = exports.CheckError = exports.EndpointError = exports.RequestFailedError = exports.ValidationError = exports.FaynoSyncError = void 0;
+class FaynoSyncError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FaynoSyncError';
+    }
+}
+exports.FaynoSyncError = FaynoSyncError;
+class ValidationError extends FaynoSyncError {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class RequestFailedError extends FaynoSyncError {
+    constructor(message) {
+        super(message);
+        this.name = 'RequestFailedError';
+    }
+}
+exports.RequestFailedError = RequestFailedError;
+class EndpointError extends RequestFailedError {
+    source;
+    endpointUrl;
+    statusCode;
+    constructor(source, endpointUrl, statusCode, cause) {
+        let msg;
+        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.source = source;
+        this.endpointUrl = endpointUrl;
+        this.statusCode = statusCode;
+        this.name = 'EndpointError';
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+exports.EndpointError = EndpointError;
+class CheckError extends RequestFailedError {
+    edgeError;
+    apiError;
+    constructor(edgeError, apiError) {
+        let msg;
+        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.edgeError = edgeError;
+        this.apiError = apiError;
+        this.name = 'CheckError';
+    }
+}
+exports.CheckError = CheckError;
+exports.ErrMissingBaseURL = new ValidationError('faynosync: missing base URL');
+exports.ErrInvalidBaseURL = new ValidationError('faynosync: invalid base URL');
+exports.ErrInvalidEdgeURL = new ValidationError('faynosync: invalid edge URL');
+exports.ErrMissingOwner = new ValidationError('faynosync: missing owner');
+exports.ErrMissingAppName = new ValidationError('faynosync: missing app name');
+exports.ErrMissingVersion = new ValidationError('faynosync: missing version');
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAEA,MAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,MAAa,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED,MAAa,aAAc,SAAQ,kBAAkB;IAEjC;IACA;IACA;IAHlB,YACkB,MAAoB,EACpB,WAAmB,EACnB,UAAmB,EACnC,KAAa;QAEb,IAAI,GAAW,CAAC;QAChB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,GAAG,GAAG,8BAA8B,WAAW,kBAAkB,UAAU,EAAE,CAAC;QAChF,CAAC;aAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,GAAG,GAAG,8BAA8B,WAAW,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,8BAA8B,WAAW,EAAE,CAAC;QACpD,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAC;QAbK,WAAM,GAAN,MAAM,CAAc;QACpB,gBAAW,GAAX,WAAW,CAAQ;QACnB,eAAU,GAAV,UAAU,CAAS;QAYnC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AArBD,sCAqBC;AAED,MAAa,UAAW,SAAQ,kBAAkB;IAE9B;IACA;IAFlB,YACkB,SAAiB,EACjB,QAAgB;QAEhC,IAAI,GAAW,CAAC;QAChB,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACtD,GAAG,GAAG,2CAA2C,SAAS,CAAC,OAAO,iBAAiB,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxG,CAAC;aAAM,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,GAAG,GAAG,2CAA2C,SAAS,CAAC,OAAO,EAAE,CAAC;QACvE,CAAC;aAAM,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAClC,GAAG,GAAG,0CAA0C,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,2BAA2B,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAC;QAbK,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAahC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAlBD,gCAkBC;AAEY,QAAA,iBAAiB,GAAG,IAAI,eAAe,CAAC,6BAA6B,CAAC,CAAC;AACvE,QAAA,iBAAiB,GAAG,IAAI,eAAe,CAAC,6BAA6B,CAAC,CAAC;AACvE,QAAA,iBAAiB,GAAG,IAAI,eAAe,CAAC,6BAA6B,CAAC,CAAC;AACvE,QAAA,eAAe,GAAG,IAAI,eAAe,CAAC,0BAA0B,CAAC,CAAC;AAClE,QAAA,iBAAiB,GAAG,IAAI,eAAe,CAAC,6BAA6B,CAAC,CAAC;AACvE,QAAA,iBAAiB,GAAG,IAAI,eAAe,CAAC,4BAA4B,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EACL,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemPlatform = exports.systemArch = exports.ValidationError = exports.RequestFailedError = exports.FaynoSyncError = exports.ErrMissingVersion = exports.ErrMissingOwner = exports.ErrMissingBaseURL = exports.ErrMissingAppName = exports.ErrInvalidEdgeURL = exports.ErrInvalidBaseURL = exports.EndpointError = exports.CheckError = exports.Client = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "CheckError", { enumerable: true, get: function () { return errors_1.CheckError; } });
+Object.defineProperty(exports, "EndpointError", { enumerable: true, get: function () { return errors_1.EndpointError; } });
+Object.defineProperty(exports, "ErrInvalidBaseURL", { enumerable: true, get: function () { return errors_1.ErrInvalidBaseURL; } });
+Object.defineProperty(exports, "ErrInvalidEdgeURL", { enumerable: true, get: function () { return errors_1.ErrInvalidEdgeURL; } });
+Object.defineProperty(exports, "ErrMissingAppName", { enumerable: true, get: function () { return errors_1.ErrMissingAppName; } });
+Object.defineProperty(exports, "ErrMissingBaseURL", { enumerable: true, get: function () { return errors_1.ErrMissingBaseURL; } });
+Object.defineProperty(exports, "ErrMissingOwner", { enumerable: true, get: function () { return errors_1.ErrMissingOwner; } });
+Object.defineProperty(exports, "ErrMissingVersion", { enumerable: true, get: function () { return errors_1.ErrMissingVersion; } });
+Object.defineProperty(exports, "FaynoSyncError", { enumerable: true, get: function () { return errors_1.FaynoSyncError; } });
+Object.defineProperty(exports, "RequestFailedError", { enumerable: true, get: function () { return errors_1.RequestFailedError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+var system_1 = require("./system");
+Object.defineProperty(exports, "systemArch", { enumerable: true, get: function () { return system_1.systemArch; } });
+Object.defineProperty(exports, "systemPlatform", { enumerable: true, get: function () { return system_1.systemPlatform; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AAGf,mCAYkB;AAXhB,oGAAA,UAAU,OAAA;AACV,uGAAA,aAAa,OAAA;AACb,2GAAA,iBAAiB,OAAA;AACjB,2GAAA,iBAAiB,OAAA;AACjB,2GAAA,iBAAiB,OAAA;AACjB,2GAAA,iBAAiB,OAAA;AACjB,yGAAA,eAAe,OAAA;AACf,2GAAA,iBAAiB,OAAA;AACjB,wGAAA,cAAc,OAAA;AACd,4GAAA,kBAAkB,OAAA;AAClB,yGAAA,eAAe,OAAA;AAEjB,mCAAsD;AAA7C,oGAAA,UAAU,OAAA;AAAE,wGAAA,cAAc,OAAA"}

package/dist/system.d.ts

@@ -0,0 +1,3 @@
+export declare function systemPlatform(): string;
+export declare function systemArch(): string;
+//# sourceMappingURL=system.d.ts.map

package/dist/system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../src/system.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/system.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemPlatform = systemPlatform;
+exports.systemArch = systemArch;
+function systemPlatform() {
+    return process.platform;
+}
+function systemArch() {
+    return process.arch;
+}
+//# sourceMappingURL=system.js.map

package/dist/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../src/system.ts"],"names":[],"mappings":";;AAAA,wCAEC;AAED,gCAEC;AAND,SAAgB,cAAc;IAC5B,OAAO,OAAO,CAAC,QAAQ,CAAC;AAC1B,CAAC;AAED,SAAgB,UAAU;IACxB,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/examples/basic/README.md

@@ -0,0 +1,17 @@
+# basic
+
+Minimal update check using the faynoSync JS SDK.
+
+Demonstrates:
+
+- Creating a `Client` with only `baseURL`
+- Using `systemPlatform()` and `systemArch()` to pass Node.js runtime values
+- Distinguishing request failures (`RequestFailedError`) from validation errors
+
+## Run
+
+```sh
+npx ts-node examples/basic/index.ts
+```
+
+Expects a faynoSync server running at `http://localhost:9000`.

package/examples/basic/index.ts

@@ -0,0 +1,75 @@
+import { Client, RequestFailedError, systemArch, systemPlatform } from '../../src';
+import type { UpdateResponse, UpdateSource } from '../../src';
+
+const client = new Client({
+  baseURL: 'http://localhost:9000',
+});
+
+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: systemPlatform(),
+      arch: systemArch(),
+    });
+  } 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/custom-fetch/README.md

@@ -0,0 +1,29 @@
+# custom-fetch
+
+Update check with a custom `fetch` function and explicit timeout.
+
+Demonstrates:
+
+- Supplying a custom `fetch` to `Client` for connection reuse via `https.Agent`
+- Setting `timeoutMs` to control per-request deadline
+- Passing `deviceId` alongside a custom transport
+
+## When to use a custom `fetch`
+
+The default `globalThis.fetch` (Node.js 18+ built-in) creates a new connection for every request. For applications that poll frequently, supply a custom `fetch` backed by an agent with `keepAlive: true` to reuse connections and reduce latency.
+
+```ts
+const client = new Client({
+  baseURL: 'https://api.example.com',
+  fetch: myFetch,   // e.g. wraps undici or node-fetch with a shared agent
+  timeoutMs: 10_000,
+});
+```
+
+## Run
+
+```sh
+npx ts-node examples/custom-fetch/index.ts
+```
+
+Expects a faynoSync server running at `http://localhost:9000`.