@edgestore/sdk 0.0.0-canary-20260730115626

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EdgeStore contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @edgestore/sdk
+
+Official low-level TypeScript SDK for the EdgeStore API.
+
+The SDK is server-only and uses EdgeStore API v2. Generated OpenAPI types stay
+internal while the package exposes a stable, resource-oriented public API.
+
+Operation and field documentation is generated from the pinned OpenAPI schema;
+SDK-specific behavior is documented on the handwritten public facade.
+
+```ts
+import { createEdgeStoreSdk } from '@edgestore/sdk';
+
+const sdk = createEdgeStoreSdk({
+  credentials: {
+    accessKey: process.env.EDGE_STORE_ACCESS_KEY!,
+    secretKey: process.env.EDGE_STORE_SECRET_KEY!,
+  },
+});
+
+const result = await sdk.runtime.uploads.upload({
+  bucket: 'documents',
+  source: pdfBlob,
+  fileName: 'invoice.pdf',
+  metadata: { invoiceId: 'invoice-123' },
+  signal,
+  onProgress: ({ percentage, phase }) => console.log(phase, percentage),
+});
+```
+
+Project credentials expose runtime resources for their current project.
+Management tokens expose management resources and runtime calls with an
+explicit `project` selector.
+
+Use `runtime.files.generateSignedReadUrls` for protected runtime reads and
+`management.files.generateAccessUrls` when management code needs readable URLs
+for public or protected files.
+
+Common runtime inputs and results are exported as named types. Types for any
+other operation can be derived from the public SDK interfaces:
+
+```ts
+import type { ManagementEdgeStoreSdk } from '@edgestore/sdk';
+
+type CreateProject =
+  ManagementEdgeStoreSdk['management']['projects']['create'];
+type CreateProjectInput = Parameters<CreateProject>[0];
+type CreateProjectOutput = Awaited<ReturnType<CreateProject>>;
+```
+
+The high-level upload helper supports automatic multipart selection, bounded
+parallelism, retries, progress, abort signals, cancellation, and processing
+polling. Lower-level upload lifecycle methods are also available.
+
+See the [EdgeStore documentation](https://edgestore.dev/docs/sdk) for runtime,
+management, error-handling, and custom transport examples.

package/dist/credentials.d.ts

@@ -0,0 +1,22 @@
+/** Project-scoped credentials used by runtime API clients. */
+export type ProjectCredentials = {
+    /** Project access key. */
+    accessKey: string;
+    /** Project secret key. */
+    secretKey: string;
+};
+/** Management token used by administrative API clients. */
+export type ManagementCredentials = {
+    /** Account- or user-owned management token. */
+    token: string;
+};
+/** Credentials accepted by {@link createEdgeStoreSdk}. */
+export type EdgeStoreCredentials = ProjectCredentials | ManagementCredentials;
+export type ClassifiedCredentials = ({
+    kind: 'project';
+} & ProjectCredentials) | ({
+    kind: 'management';
+} & ManagementCredentials);
+export declare function classifyCredentials(credentials: EdgeStoreCredentials): ClassifiedCredentials;
+export declare function getAuthorizationHeader(credentials: ClassifiedCredentials): string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAAG;IAClC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,qBAAqB,CAAC;AAE9E,MAAM,MAAM,qBAAqB,GAC7B,CAAC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,kBAAkB,CAAC,GAC1C,CAAC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG,qBAAqB,CAAC,CAAC;AAErD,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,oBAAoB,GAChC,qBAAqB,CAmBvB;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,qBAAqB,GACjC,MAAM,CAWR"}

package/dist/credentials.js

@@ -0,0 +1,37 @@
+/** Project-scoped credentials used by runtime API clients. */ function classifyCredentials(credentials) {
+    const values = credentials;
+    const token = values.token;
+    const accessKey = values.accessKey;
+    const secretKey = values.secretKey;
+    if (token !== undefined) {
+        if (accessKey !== undefined || secretKey !== undefined) {
+            throw new TypeError('EdgeStore credentials cannot contain both a management token and project keys.');
+        }
+        assertCredential(token, 'token');
+        return {
+            kind: 'management',
+            token
+        };
+    }
+    assertCredential(accessKey, 'accessKey');
+    assertCredential(secretKey, 'secretKey');
+    return {
+        kind: 'project',
+        accessKey,
+        secretKey
+    };
+}
+function getAuthorizationHeader(credentials) {
+    if (credentials.kind === 'management') {
+        return `Bearer ${credentials.token}`;
+    }
+    const encodedCredentials = Buffer.from(`${credentials.accessKey}:${credentials.secretKey}`, 'utf8').toString('base64');
+    return `Basic ${encodedCredentials}`;
+}
+function assertCredential(value, name) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`EdgeStore credential \`${name}\` must not be empty.`);
+    }
+}
+
+export { classifyCredentials, getAuthorizationHeader };

package/dist/errors.d.ts

@@ -0,0 +1,65 @@
+/** Base class for errors raised by the EdgeStore SDK. */
+export declare class EdgeStoreError extends Error {
+    readonly name: string;
+}
+/** A non-success response returned by the EdgeStore API. */
+export declare class EdgeStoreApiError extends EdgeStoreError {
+    readonly name = "EdgeStoreApiError";
+    /** HTTP response status. */
+    readonly status: number;
+    /** Stable machine-readable API error code. */
+    readonly code: string;
+    /** Structured error details, when provided by the API. */
+    readonly details: unknown;
+    /** EdgeStore request identifier for tracing and support. */
+    readonly requestId: string | undefined;
+    /** Server-requested retry delay parsed from `Retry-After`. */
+    readonly retryAfterSeconds: number | undefined;
+    constructor(options: {
+        message: string;
+        status: number;
+        code: string;
+        details?: unknown;
+        requestId?: string;
+        retryAfterSeconds?: number;
+    });
+}
+/** A request that could not reach the API or upload destination. */
+export declare class EdgeStoreNetworkError extends EdgeStoreError {
+    readonly name = "EdgeStoreNetworkError";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A request or upload canceled through an `AbortSignal`. */
+export declare class EdgeStoreAbortError extends EdgeStoreError {
+    readonly name = "EdgeStoreAbortError";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** Base class for failures tied to an upload created by the SDK. */
+export declare class EdgeStoreUploadError extends EdgeStoreError {
+    readonly name: string;
+    /** Upload identifier that can be used for diagnostics. */
+    readonly uploadId: string;
+    constructor(message: string, uploadId: string, options?: ErrorOptions);
+}
+/** An upload canceled before it reached a completed state. */
+export declare class EdgeStoreUploadCanceledError extends EdgeStoreUploadError {
+    readonly name = "EdgeStoreUploadCanceledError";
+}
+/** An upload that did not finish server-side processing before its deadline. */
+export declare class EdgeStoreUploadProcessingTimeoutError extends EdgeStoreUploadError {
+    readonly name = "EdgeStoreUploadProcessingTimeoutError";
+}
+/** Failure returned for a singular file mutation. */
+export declare class EdgeStoreFileMutationError<TFileReference = {
+    id: string;
+} | {
+    key: string;
+} | {
+    url: string;
+}, TCode extends string = 'FILE_NOT_CONFIRMABLE' | 'FILE_NOT_DELETABLE' | 'FILE_NOT_RESTORABLE' | 'INVALID_FILE_REF'> extends EdgeStoreError {
+    readonly code: TCode;
+    readonly fileRef: TFileReference;
+    readonly name = "EdgeStoreFileMutationError";
+    constructor(code: TCode, message: string, fileRef: TFileReference);
+}
+//# 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,yDAAyD;AACzD,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,EAAE,MAAM,CAAoB;CACnD;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,SAAkB,IAAI,uBAAuB;IAC7C,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEnC,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B;CAQF;AAED,oEAAoE;AACpE,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,SAAkB,IAAI,2BAA2B;gBAErC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,6DAA6D;AAC7D,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,SAAkB,IAAI,yBAAyB;gBAG7C,OAAO,SAAuC,EAC9C,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED,oEAAoE;AACpE,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,SAAkB,IAAI,EAAE,MAAM,CAA0B;IACxD,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAItE;AAED,8DAA8D;AAC9D,qBAAa,4BAA6B,SAAQ,oBAAoB;IACpE,SAAkB,IAAI,kCAAkC;CACzD;AAED,gFAAgF;AAChF,qBAAa,qCAAsC,SAAQ,oBAAoB;IAC7E,SAAkB,IAAI,2CAA2C;CAClE;AAED,qDAAqD;AACrD,qBAAa,0BAA0B,CACrC,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACnE,KAAK,SAAS,MAAM,GAChB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,kBAAkB,CACtB,SAAQ,cAAc;IAIpB,QAAQ,CAAC,IAAI,EAAE,KAAK;IAEpB,QAAQ,CAAC,OAAO,EAAE,cAAc;IALlC,SAAkB,IAAI,gCAAgC;gBAG3C,IAAI,EAAE,KAAK,EACpB,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,cAAc;CAInC"}

package/dist/errors.js

@@ -0,0 +1,59 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else obj[key] = value;
+    return obj;
+}
+/** Base class for errors raised by the EdgeStore SDK. */ class EdgeStoreError extends Error {
+    constructor(...args){
+        super(...args), _define_property(this, "name", 'EdgeStoreError');
+    }
+}
+/** A non-success response returned by the EdgeStore API. */ class EdgeStoreApiError extends EdgeStoreError {
+    constructor(options){
+        super(options.message), _define_property(this, "name", 'EdgeStoreApiError'), /** HTTP response status. */ _define_property(this, "status", void 0), /** Stable machine-readable API error code. */ _define_property(this, "code", void 0), /** Structured error details, when provided by the API. */ _define_property(this, "details", void 0), /** EdgeStore request identifier for tracing and support. */ _define_property(this, "requestId", void 0), /** Server-requested retry delay parsed from `Retry-After`. */ _define_property(this, "retryAfterSeconds", void 0);
+        this.status = options.status;
+        this.code = options.code;
+        this.details = options.details;
+        this.requestId = options.requestId;
+        this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+}
+/** A request that could not reach the API or upload destination. */ class EdgeStoreNetworkError extends EdgeStoreError {
+    constructor(message, options){
+        super(message, options), _define_property(this, "name", 'EdgeStoreNetworkError');
+    }
+}
+/** A request or upload canceled through an `AbortSignal`. */ class EdgeStoreAbortError extends EdgeStoreError {
+    constructor(message = 'The EdgeStore request was aborted.', options){
+        super(message, options), _define_property(this, "name", 'EdgeStoreAbortError');
+    }
+}
+/** Base class for failures tied to an upload created by the SDK. */ class EdgeStoreUploadError extends EdgeStoreError {
+    constructor(message, uploadId, options){
+        super(message, options), _define_property(this, "name", 'EdgeStoreUploadError'), /** Upload identifier that can be used for diagnostics. */ _define_property(this, "uploadId", void 0);
+        this.uploadId = uploadId;
+    }
+}
+/** An upload canceled before it reached a completed state. */ class EdgeStoreUploadCanceledError extends EdgeStoreUploadError {
+    constructor(...args){
+        super(...args), _define_property(this, "name", 'EdgeStoreUploadCanceledError');
+    }
+}
+/** An upload that did not finish server-side processing before its deadline. */ class EdgeStoreUploadProcessingTimeoutError extends EdgeStoreUploadError {
+    constructor(...args){
+        super(...args), _define_property(this, "name", 'EdgeStoreUploadProcessingTimeoutError');
+    }
+}
+/** Failure returned for a singular file mutation. */ class EdgeStoreFileMutationError extends EdgeStoreError {
+    constructor(code, message, fileRef){
+        super(message), _define_property(this, "code", void 0), _define_property(this, "fileRef", void 0), _define_property(this, "name", void 0), this.code = code, this.fileRef = fileRef, this.name = 'EdgeStoreFileMutationError';
+    }
+}
+
+export { EdgeStoreAbortError, EdgeStoreApiError, EdgeStoreError, EdgeStoreFileMutationError, EdgeStoreNetworkError, EdgeStoreUploadCanceledError, EdgeStoreUploadError, EdgeStoreUploadProcessingTimeoutError };