@fastrelay/js-sdk 0.1.0

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+import type { FeedActivityQuery } from './types.ts';
+export type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined>;
+export type QueryMap = Record<string, unknown>;
+export declare function toAbsoluteUrl(baseUrl: string, path: string, query?: QueryMap): string;
+export declare function buildFeedActivityQuery(options?: FeedActivityQuery): QueryMap;
+export type FeedTarget = string | {
+    group: string;
+    id: string;
+};
+export declare function resolveFeedTarget(target: unknown): string;
+export declare function splitFeedId(feedId: string): [group: string, id: string];
+export declare function parseJsonSafely(text: string): unknown;

package/dist/utils.js

@@ -0,0 +1,77 @@
+export function toAbsoluteUrl(baseUrl, path, query) {
+    const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+    const url = new URL(normalizedPath, normalizedBase);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value === null || value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (item !== null && item !== undefined) {
+                        url.searchParams.append(key, String(item));
+                    }
+                }
+            }
+            else {
+                url.searchParams.append(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+export function buildFeedActivityQuery(options) {
+    if (!options)
+        return {};
+    const query = {};
+    if ('limit' in options)
+        query.limit = options.limit;
+    if ('cursor' in options)
+        query.cursor = options.cursor;
+    if ('view' in options)
+        query.view = options.view;
+    if ('markSeen' in options)
+        query.markSeen = options.markSeen;
+    if ('markRead' in options) {
+        const markRead = options.markRead;
+        query.markRead = Array.isArray(markRead) ? markRead.join(',') : markRead;
+    }
+    if (options.filter && typeof options.filter === 'object') {
+        for (const [key, value] of Object.entries(options.filter)) {
+            query[`filter[${key}]`] = value;
+        }
+    }
+    return query;
+}
+export function resolveFeedTarget(target) {
+    if (typeof target === 'string' && target.length > 0) {
+        return target;
+    }
+    if (target && typeof target === 'object') {
+        const { group, id } = target;
+        if (typeof group === 'string' &&
+            group.length > 0 &&
+            typeof id === 'string' &&
+            id.length > 0) {
+            return `${group}:${id}`;
+        }
+    }
+    throw new TypeError("target must be a feed string like 'user:john' or {group, id}.");
+}
+export function splitFeedId(feedId) {
+    const separatorIndex = feedId.indexOf(':');
+    if (separatorIndex <= 0 || separatorIndex === feedId.length - 1) {
+        throw new TypeError(`Invalid feed id '${feedId}'. Expected format '{group}:{id}'.`);
+    }
+    return [feedId.slice(0, separatorIndex), feedId.slice(separatorIndex + 1)];
+}
+export function parseJsonSafely(text) {
+    if (text.trim() === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/video-upload.d.ts

@@ -0,0 +1,44 @@
+import type { FastrelayClient } from './client.ts';
+export interface FastrelayVideoUploadProgress {
+    bytesUploaded: number;
+    totalBytes: number;
+    fraction: number;
+}
+export interface FastrelayVideoUploadResult {
+    videoId: string;
+    uploadUrl: string;
+    bytesUploaded: number;
+}
+export declare class FastrelayVideoUploadError extends Error {
+    readonly statusCode?: number;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Drives a tus 1.0.0 upload of `data` to `uploadUrl` (the pre-authorized
+ * Cloudflare Stream endpoint returned by createVideoUploadUrl). Calls
+ * `onProgress` after each PATCH chunk; resolves with the total bytes accepted.
+ */
+export declare function tusUploadBytes({ uploadUrl, data, chunkSize, onProgress, fetchImpl, }: {
+    uploadUrl: string;
+    data: Uint8Array | ArrayBuffer;
+    chunkSize?: number;
+    onProgress?: (progress: FastrelayVideoUploadProgress) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<number>;
+/**
+ * High-level helper: mints a tus upload URL via the backend, then uploads
+ * `data` directly to Cloudflare Stream. The caller listens for `video.ready`
+ * on the realtime channel (or polls client.getVideo) for the final state.
+ */
+export declare function uploadVideoBytes(client: FastrelayClient, { data, filename, mimeType, chunkSize, onProgress, fetchImpl, }: {
+    data: Uint8Array | ArrayBuffer;
+    filename: string;
+    mimeType: string;
+    chunkSize?: number;
+    onProgress?: (progress: FastrelayVideoUploadProgress) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<FastrelayVideoUploadResult>;

package/dist/video-upload.js

@@ -0,0 +1,97 @@
+export class FastrelayVideoUploadError extends Error {
+    statusCode;
+    cause;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'FastrelayVideoUploadError';
+        this.statusCode = options.statusCode;
+        this.cause = options.cause;
+    }
+}
+const DEFAULT_CHUNK_SIZE = 50 * 1024 * 1024;
+/**
+ * Drives a tus 1.0.0 upload of `data` to `uploadUrl` (the pre-authorized
+ * Cloudflare Stream endpoint returned by createVideoUploadUrl). Calls
+ * `onProgress` after each PATCH chunk; resolves with the total bytes accepted.
+ */
+export async function tusUploadBytes({ uploadUrl, data, chunkSize = DEFAULT_CHUNK_SIZE, onProgress, fetchImpl = fetch, }) {
+    if (uploadUrl.trim() === '') {
+        throw new TypeError('uploadUrl must not be empty.');
+    }
+    if (chunkSize <= 0) {
+        throw new TypeError('chunkSize must be positive.');
+    }
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const total = bytes.byteLength;
+    const report = (bytesUploaded) => onProgress?.({
+        bytesUploaded,
+        totalBytes: total,
+        fraction: total <= 0 ? 0 : Math.min(1, Math.max(0, bytesUploaded / total)),
+    });
+    let offset = 0;
+    report(0);
+    while (offset < total) {
+        const end = Math.min(offset + chunkSize, total);
+        const chunk = bytes.slice(offset, end);
+        const response = await fetchImpl(uploadUrl, {
+            method: 'PATCH',
+            headers: {
+                'tus-resumable': '1.0.0',
+                'upload-offset': String(offset),
+                'content-type': 'application/offset+octet-stream',
+            },
+            body: chunk,
+        });
+        if (response.status !== 204 && response.status !== 200) {
+            const body = await response.text().catch(() => '');
+            throw new FastrelayVideoUploadError(`tus PATCH failed: ${response.status} ${response.statusText} ${body}`.trim(), { statusCode: response.status });
+        }
+        const reportedOffset = Number.parseInt(response.headers.get('upload-offset') ?? '', 10);
+        const nextOffset = Number.isNaN(reportedOffset)
+            ? offset + chunk.byteLength
+            : reportedOffset;
+        // A non-advancing offset would loop forever; one past `total` would
+        // report success for bytes the server never accepted.
+        if (nextOffset <= offset || nextOffset > total) {
+            throw new FastrelayVideoUploadError(`tus server reported invalid upload-offset ${nextOffset} ` +
+                `(previous offset ${offset}, total ${total}).`, { statusCode: response.status });
+        }
+        offset = nextOffset;
+        report(offset);
+    }
+    return offset;
+}
+/**
+ * High-level helper: mints a tus upload URL via the backend, then uploads
+ * `data` directly to Cloudflare Stream. The caller listens for `video.ready`
+ * on the realtime channel (or polls client.getVideo) for the final state.
+ */
+export async function uploadVideoBytes(client, { data, filename, mimeType, chunkSize = DEFAULT_CHUNK_SIZE, onProgress, fetchImpl, }) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.byteLength === 0) {
+        throw new TypeError('uploadVideoBytes requires non-empty data.');
+    }
+    if (filename.trim() === '') {
+        throw new TypeError('uploadVideoBytes requires a non-empty filename.');
+    }
+    if (!mimeType.trim().toLowerCase().startsWith('video/')) {
+        throw new TypeError(`uploadVideoBytes requires a video/* mimeType (got "${mimeType}").`);
+    }
+    const mint = await client.createVideoUploadUrl({
+        filename,
+        sizeBytes: bytes.byteLength,
+        mimeType,
+    });
+    const uploaded = await tusUploadBytes({
+        uploadUrl: mint.uploadUrl,
+        data: bytes,
+        chunkSize,
+        onProgress,
+        fetchImpl,
+    });
+    return {
+        videoId: mint.videoId,
+        uploadUrl: mint.uploadUrl,
+        bytesUploaded: uploaded,
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@fastrelay/js-sdk",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for fastrelay feed APIs.",
+  "homepage": "https://github.com/The-Nexus-Collective/fastrelay-js-sdk",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test 'test/*.test.ts'"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}