@stackshift-cloud/sdk 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @stackshift-cloud/sdk
+
+Official JavaScript and TypeScript SDK for StackShift.
+
+## Install
+
+```bash
+npm install @stackshift-cloud/sdk
+```
+
+## Upload an asset
+
+```ts
+import { StackShift } from '@stackshift-cloud/sdk'
+import { readFile } from 'node:fs/promises'
+
+const stackshift = new StackShift()
+
+const file = new Blob([await readFile('./avatar.png')], { type: 'image/png' })
+
+const asset = await stackshift.assets.upload(file, {
+  folder: 'avatars',
+  visibility: 'public',
+  metadata: { userId: 'user_123' },
+})
+
+console.log(asset.url)
+```
+
+You do not pass a deployed StackShift project ID. The API key identifies the StackShift account, and StackShift resolves the default asset space internally.
+
+## Private assets
+
+```ts
+const asset = await stackshift.assets.upload(file, {
+  bucket: 'imports',
+  key: 'customers.csv',
+  visibility: 'private',
+})
+
+const signed = await stackshift.assets.signedUrl(asset.id, {
+  expiresIn: '10m',
+  maxDownloads: 1,
+})
+
+console.log(signed.url)
+```
+
+## Direct browser uploads
+
+Create a signed upload URL on your server:
+
+```ts
+const upload = await stackshift.assets.createUploadSession({
+  bucket: 'avatars',
+  key: 'users/user_123.png',
+  visibility: 'public',
+  expiresIn: '10m',
+  maxBytes: 5_000_000,
+})
+```
+
+Then upload from the browser:
+
+```ts
+await fetch(upload.url, {
+  method: upload.method,
+  body: file,
+  headers: { 'Content-Type': file.type },
+})
+```
+
+StackShift chooses storage nodes, writes to StackShift-owned disks, replicates internally, and returns CDN-ready asset URLs. SDK users never choose storage nodes and never receive disk paths.

package/dist/assets.d.ts

@@ -0,0 +1,16 @@
+import type { StackShift } from './client';
+import type { Asset, AssetListOptions, AssetListResult, AssetSignedUploadUrl, AssetSignedUploadUrlOptions, AssetSignedUrl, AssetSignedUrlOptions, AssetUploadOptions } from './types';
+export declare class AssetsClient {
+    private readonly client;
+    constructor(client: StackShift);
+    upload(file: Blob, options?: AssetUploadOptions): Promise<Asset>;
+    list(options?: AssetListOptions): Promise<AssetListResult>;
+    get(assetId: string): Promise<Asset>;
+    delete(assetId: string): Promise<{
+        deleted: boolean;
+    }>;
+    replace(assetId: string, file: Blob, options?: Pick<AssetUploadOptions, 'cacheControl' | 'metadata'>): Promise<Asset>;
+    signedUrl(assetId: string, options: AssetSignedUrlOptions): Promise<AssetSignedUrl>;
+    signedUploadUrl(options?: AssetSignedUploadUrlOptions): Promise<AssetSignedUploadUrl>;
+    createUploadSession(options?: AssetSignedUploadUrlOptions): Promise<AssetSignedUploadUrl>;
+}

package/dist/assets.js

@@ -0,0 +1,81 @@
+export class AssetsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    upload(file, options = {}) {
+        return this.client.request('/assets/upload', {
+            method: 'POST',
+            body: assetForm(file, options),
+        });
+    }
+    list(options = {}) {
+        const query = new URLSearchParams();
+        append(query, 'bucket', options.bucket);
+        append(query, 'prefix', options.prefix);
+        append(query, 'visibility', options.visibility);
+        append(query, 'limit', options.limit);
+        append(query, 'cursor', options.cursor);
+        const suffix = query.toString();
+        return this.client.request(`/assets${suffix ? `?${suffix}` : ''}`);
+    }
+    get(assetId) {
+        return this.client.request(`/assets/${encodeURIComponent(assetId)}`);
+    }
+    delete(assetId) {
+        return this.client.request(`/assets/${encodeURIComponent(assetId)}`, {
+            method: 'DELETE',
+        });
+    }
+    replace(assetId, file, options = {}) {
+        return this.client.request(`/assets/${encodeURIComponent(assetId)}/replace`, {
+            method: 'PUT',
+            body: assetForm(file, options),
+        });
+    }
+    signedUrl(assetId, options) {
+        return this.client.request(`/assets/${encodeURIComponent(assetId)}/signed-url`, {
+            method: 'POST',
+            body: {
+                expiresIn: options.expiresIn,
+                maxDownloads: options.maxDownloads,
+            },
+        });
+    }
+    signedUploadUrl(options = {}) {
+        return this.createUploadSession(options);
+    }
+    createUploadSession(options = {}) {
+        return this.client.request('/assets/upload-sessions', {
+            method: 'POST',
+            body: {
+                bucket: options.bucket,
+                key: options.key,
+                folder: options.folder,
+                visibility: options.visibility,
+                cacheControl: options.cacheControl,
+                metadata: options.metadata,
+                expiresIn: options.expiresIn,
+                maxBytes: options.maxBytes,
+            },
+        });
+    }
+}
+function assetForm(file, options) {
+    const body = new FormData();
+    body.append('file', file);
+    append(body, 'bucket', options.bucket);
+    append(body, 'key', options.key);
+    append(body, 'folder', options.folder);
+    append(body, 'visibility', options.visibility);
+    append(body, 'cacheControl', options.cacheControl);
+    if (options.metadata) {
+        body.append('metadata', JSON.stringify(options.metadata));
+    }
+    return body;
+}
+function append(target, key, value) {
+    if (value !== undefined && value !== null && value !== '') {
+        target.append(key, String(value));
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import { AssetsClient } from './assets';
+import { ProjectsClient } from './projects';
+import type { StackShiftOptions } from './types';
+export declare class StackShift {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly projects: ProjectsClient;
+    readonly assets: AssetsClient;
+    private readonly fetcher;
+    constructor(options?: StackShiftOptions);
+    request<T>(path: string, init?: {
+        method?: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,57 @@
+import { AssetsClient } from './assets';
+import { ProjectsClient } from './projects';
+const defaultBaseUrl = 'https://api.stackshift.cloud/api/v1';
+export class StackShift {
+    apiKey;
+    baseUrl;
+    projects;
+    assets;
+    fetcher;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? env('STACKSHIFT_API_KEY');
+        if (!apiKey) {
+            throw new Error('StackShift SDK requires an apiKey');
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/$/, '');
+        this.fetcher = options.fetch ?? fetch;
+        this.projects = new ProjectsClient(this);
+        this.assets = new AssetsClient(this);
+    }
+    async request(path, init = {}) {
+        const isFormData = typeof FormData !== 'undefined' && init.body instanceof FormData;
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method: init.method ?? 'GET',
+            headers: stripUndefined({
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': isFormData ? undefined : 'application/json',
+                ...init.headers,
+            }),
+            body: (init.body === undefined ? undefined : isFormData ? init.body : JSON.stringify(stripUndefined(init.body))),
+        });
+        const raw = await response.text();
+        const parsed = raw ? JSON.parse(raw) : null;
+        if (!response.ok) {
+            throw new Error(parsed?.message ?? parsed?.error ?? `StackShift API request failed with ${response.status}`);
+        }
+        if (parsed && typeof parsed === 'object' && 'success' in parsed && 'data' in parsed) {
+            return parsed.data;
+        }
+        return parsed;
+    }
+}
+function env(key) {
+    const maybeProcess = globalThis.process;
+    return maybeProcess?.env?.[key];
+}
+function stripUndefined(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripUndefined);
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .map(([key, item]) => [key, stripUndefined(item)]));
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { StackShift } from './client';
+export { AssetsClient } from './assets';
+export { ProjectsClient } from './projects';
+export type { Asset, AssetListOptions, AssetListResult, AssetSignedUploadUrl, AssetSignedUploadUrlOptions, AssetSignedUrl, AssetSignedUrlOptions, AssetUploadOptions, AssetVisibility, JsonValue, Project, ProjectListOptions, StackShiftOptions, } from './types';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { StackShift } from './client';
+export { AssetsClient } from './assets';
+export { ProjectsClient } from './projects';

package/dist/projects.d.ts

@@ -0,0 +1,7 @@
+import type { StackShift } from './client';
+import type { Project, ProjectListOptions } from './types';
+export declare class ProjectsClient {
+    private readonly client;
+    constructor(client: StackShift);
+    list(options?: ProjectListOptions): Promise<Project[]>;
+}

package/dist/projects.js

@@ -0,0 +1,18 @@
+export class ProjectsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(options = {}) {
+        const query = new URLSearchParams();
+        append(query, 'page', options.page);
+        append(query, 'per_page', options.perPage);
+        const suffix = query.toString();
+        return this.client.request(`/projects/${suffix ? `?${suffix}` : ''}`);
+    }
+}
+function append(target, key, value) {
+    if (value !== undefined && value !== null && value !== '') {
+        target.append(key, String(value));
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type AssetVisibility = 'public' | 'private';
+export interface StackShiftOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface Project {
+    id: string;
+    name: string;
+    status?: string;
+    url?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface ProjectListOptions {
+    page?: number;
+    perPage?: number;
+}
+export interface Asset {
+    id: string;
+    bucket: string;
+    key: string;
+    original_name: string;
+    mime_type: string;
+    size: number;
+    checksum_sha256: string;
+    visibility: AssetVisibility;
+    status: 'uploading' | 'available' | 'deleted' | 'failed';
+    replication_status: 'pending' | 'replicated' | 'degraded' | 'failed';
+    metadata?: Record<string, JsonValue>;
+    cache_control?: string;
+    url?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetUploadOptions {
+    bucket?: string;
+    key?: string;
+    folder?: string;
+    visibility?: AssetVisibility;
+    cacheControl?: string;
+    metadata?: Record<string, JsonValue>;
+}
+export interface AssetListOptions {
+    bucket?: string;
+    prefix?: string;
+    visibility?: AssetVisibility;
+    limit?: number;
+    cursor?: string;
+}
+export interface AssetListResult {
+    assets: Asset[];
+    total: number;
+    next_cursor?: string;
+}
+export interface AssetSignedUrlOptions {
+    expiresIn: string;
+    maxDownloads?: number;
+}
+export interface AssetSignedUrl {
+    url: string;
+    expires_at: string;
+}
+export interface AssetSignedUploadUrlOptions extends AssetUploadOptions {
+    expiresIn?: string;
+    maxBytes?: number;
+}
+export interface AssetSignedUploadUrl {
+    upload_session_id: string;
+    url: string;
+    method: 'PUT';
+    expires_at: string;
+    max_bytes: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@stackshift-cloud/sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript and TypeScript SDK for StackShift.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}