diff --git a/README.md b/README.md index 667f299..04486e3 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,79 @@ -# Codex SDK +# Codex SDK The Codex SDK provides an API for interacting with the Codex decentralized storage network. -The SDK has a small bundle size and support tree shaking. +The SDK has a small bundle size and support tree shaking. -## Import +## Import ```js import { Codex } from "@codex/sdk-js"; ``` -or +or ```js const { Codex } = require("@codex/sdk-js"); ``` -## How to use +## How to use -To create a Codex instance, provide the REST API url to interact with the Codex client: +To create a Codex instance, provide the REST API url to interact with the Codex client: ```js -const codex = new Codex("http://localhost:3000") +const codex = new Codex("http://localhost:3000"); ``` To use a module, you need to use the await syntax. If the module is not loaded yet, it will be imported first and then cached in memory. ```js -const marketplace = await codex.marketplace() +const marketplace = await codex.marketplace(); ``` -### Error handling +### Error handling The SDK provides a type called `SafeValue` for error handling instead of throwing errors. It is inspired by Go's "error as value" concept. If the value represents an error, `error` is true and `data` will contain the error. If the value is not an error, `error` is false and `data` will contain the requested data. -The error type is a [CodexError](./src/errors/errors.ts#L15) which can be error object of 3 types: +The [CodexError](./src/errors/errors.ts#L16) contains a message and 3 optionals properties: -* `error`: Object containing the error message -* `api`: Object containing the api error message and the status code -* `validation`: Object containing the error message and a field `errors` of type [ValidationError](./src/errors/errors.ts#L3) containing the error message for each fields. +- `code`: The (http) code error when it comes from a request +- `errors`: A {ValidationError} array when it comes from an object validation process +- `stack`: The error stack when the CodexError results from a error thrown -Example: +Example: ```js -const slots = marketplace.activeSlots(); +const slots = marketplace.activeSlots(); if (slots.error) { - // Do something to handle the error in slots.data - return + // Do something to handle the error in slots.data + return; } // Access the slots within slots.data. ``` -### Marketplace +### Marketplace -The following API assume that you have already a marketplace module loaded, example: +The following API assume that you have already a marketplace module loaded, example: ```js -const codex = new Codex("http://localhost:3000") -const marketplace = await codex.marketplace() +const codex = new Codex("http://localhost:3000"); +const marketplace = await codex.marketplace(); ``` #### activeSlots() Returns active slots. -- returns Promise<[CodexSlot](./src/marketplace/types.ts#L86)[]> +- returns Promise<[CodexSlot](./src/marketplace/types.ts#L86)[]> -Example: +Example: ```js -const slots = await marketplace.activeSlots(); +const slots = await marketplace.activeSlots(); ``` #### activeSlot(slotId) @@ -83,24 +83,23 @@ Returns active slot with id {slotId} for the host. - slotId (string, required) - returns Promise<[CodexSlot](./src/marketplace/types.ts#L86)[]> -Example: +Example: ```js -const slotId= "AB9........" -const slot = await marketplace.activeSlot(slotId); +const slotId = "AB9........"; +const slot = await marketplace.activeSlot(slotId); ``` - #### availabilities Returns storage that is for sale. - returns Promise<[CodexAvailability](./src/marketplace/types.ts#L100)> -Example: +Example: ```js -const availabilities = await marketplace.availabilities(); +const availabilities = await marketplace.availabilities(); ``` #### createAvailability @@ -108,17 +107,17 @@ const availabilities = await marketplace.availabilities(); Offers storage for sale. - input ([CodexCreateAvailabilityInput](./src/marketplace/types.ts#L133), required) -- returns Promise<[CodexAvailabilityCreateResponse](./src/marketplace/types.ts#L124)[]> +- returns Promise<[CodexAvailabilityCreateResponse](./src/marketplace/types.ts#L124)[]> -Example: +Example: ```js const response = await marketplace.createAvailability({ - maxCollateral: 1, - totalSize: 3000, - minPrice: 100, - duration: 100, -}); + maxCollateral: 1, + totalSize: 3000, + minPrice: 100, + duration: 100, +}); ``` #### reservations @@ -126,48 +125,45 @@ const response = await marketplace.createAvailability({ Return list of reservations for ongoing Storage Requests that the node hosts. - availabilityId (string, required) -- returns Promise<[CodexReservation](./src/marketplace/types.ts#L152)[]> +- returns Promise<[CodexReservation](./src/marketplace/types.ts#L156)[]> -Example: +Example: ```js -const reservations = await marketplace.reservations("Ox..."); +const reservations = await marketplace.reservations("Ox..."); ``` - #### createStorageRequest Creates a new Request for storage -- input ([CodexCreateStorageRequestInput](./src/marketplace/types.ts#L182), required) -- returns Promise<[CodexCreateStorageRequestResponse](./src/marketplace/types.ts#L195)[]> +- input ([CodexCreateStorageRequestInput](./src/marketplace/types.ts#L186), required) +- returns Promise<[CodexCreateStorageRequestResponse](./src/marketplace/types.ts#L201)[]> -Example: +Example: ```js const request = await marketplace.createStorageRequest({ - duration: 3000, - reward: 100, - proofProbability: 1, - nodes: 1, - tolerance: 0, - collateral: 100, - expiry: 3000 -}); + duration: 3000, + reward: 100, + proofProbability: 1, + nodes: 1, + tolerance: 0, + collateral: 100, + expiry: 3000, +}); ``` - #### purchaseIds Returns list of purchase IDs - returns Promise - -Example: +Example: ```js -const ids = await marketplace.purchaseIds(); +const ids = await marketplace.purchaseIds(); ``` #### purchaseDetail @@ -175,11 +171,11 @@ const ids = await marketplace.purchaseIds(); Returns purchase details - purchaseId (string, required) -- returns Promise<[CodexPurchase](./src/marketplace/types.ts#L168)[]> +- returns Promise<[CodexPurchase](./src/marketplace/types.ts#L172)[]> -Example: +Example: ```js -const purchaseId = "Ox........" -const purchase = await marketplace.purchaseDetail(purchaseId); +const purchaseId = "Ox........"; +const purchase = await marketplace.purchaseDetail(purchaseId); ``` diff --git a/src/errors/errors.ts b/src/errors/errors.ts index 7ce6622..337f600 100644 --- a/src/errors/errors.ts +++ b/src/errors/errors.ts @@ -8,27 +8,17 @@ type ValidationError = { }; /** - * The CodexError which can be error object of 3 types: - * `error`: Object containing the error message - * `api`: Object containing the api error message and the status code - * `validation`: Object containing the error message and a field `errors` of type ValidationError - * containing the error message for each fields. + * The CodexError contains a message and 3 optionals properties: + * `code`: The (http) code error when it comes from a request + * `errors`: A {ValidationError} array when it comes from an object validation process + * `stack`: The error stack when the CodexError results from a error thrown */ -export type CodexError = - | { - type: "error"; - message: string; - } - | { - type: "api"; - message: string; - status: number; - } - | { - type: "validation"; - message: string; - errors: ValidationError[]; - }; +export type CodexError = { + message: string; + code?: number; + errors?: ValidationError[]; + stack?: string; +}; export const CodexValibotIssuesMap = (issues: InferIssue[]) => issues.map((i) => ({ diff --git a/src/fetch-safe/fetch-safe.ts b/src/fetch-safe/fetch-safe.ts index de5da48..649efec 100644 --- a/src/fetch-safe/fetch-safe.ts +++ b/src/fetch-safe/fetch-safe.ts @@ -3,7 +3,7 @@ import { type SafeValue } from "../values/values"; export const Fetch = { async safe( url: string, - init: RequestInit + init: RequestInit, ): Promise> { const res = await fetch(url, init); @@ -13,9 +13,8 @@ export const Fetch = { return { error: true, data: { - type: "api", message, - status: res.status, + code: res.status, }, }; } @@ -25,11 +24,12 @@ export const Fetch = { return { error: false, data: json }; } catch (e) { + const opts = e instanceof Error && e.stack ? { stack: e.stack } : {}; return { error: true, data: { - type: "error", message: e instanceof Error ? e.message : "JSON parsing error :" + e, + ...opts, }, }; } diff --git a/src/marketplace/marketplace.ts b/src/marketplace/marketplace.ts index 63225ba..98b2692 100644 --- a/src/marketplace/marketplace.ts +++ b/src/marketplace/marketplace.ts @@ -67,7 +67,6 @@ export class Marketplace { return { error: true, data: { - type: "validation", message: "Cannot validate the input", errors: CodexValibotIssuesMap(result.issues), }, @@ -98,7 +97,6 @@ export class Marketplace { return { error: true, data: { - type: "validation", message: "Cannot validate the input", errors: CodexValibotIssuesMap(result.issues), }, @@ -168,7 +166,6 @@ export class Marketplace { return { error: true, data: { - type: "validation", message: "Cannot validate the input", errors: CodexValibotIssuesMap(result.issues), },