@space-df/sdk 0.0.1-dev.3.3 → 0.0.1-dev.5

package/dist/src/error.ts

@@ -0,0 +1,134 @@
+import { castToError, Headers } from './core';
+
+export class SpaceDFError extends Error {}
+
+export class APIError extends SpaceDFError {
+    readonly status: number | undefined;
+    readonly headers: Headers | undefined;
+    readonly error: object | undefined;
+
+    constructor(status: number | undefined, error: object | undefined, message: string | undefined, headers: Headers | undefined) {
+        super(`${APIError.makeMessage(status, error, message)}`);
+        this.status = status;
+        this.headers = headers;
+        this.error = error;
+    }
+
+    private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+        const msg = error?.message
+            ? typeof error.message === 'string'
+                ? error.message
+                : JSON.stringify(error.message)
+            : error
+              ? JSON.stringify(error)
+              : message;
+
+        if (status && msg) {
+            return `${status} ${msg}`;
+        }
+        if (status) {
+            return `${status} status code (no body)`;
+        }
+        if (msg) {
+            return msg;
+        }
+        return '(no status code or body)';
+    }
+
+    static generate(status: number | undefined, errorResponse: object | undefined, message: string | undefined, headers: Headers | undefined) {
+        if (!status) {
+            return new APIConnectionError({ message, cause: castToError(errorResponse) });
+        }
+
+        const error = errorResponse as Record<string, any>;
+
+        if (status === 400) {
+            return new BadRequestError(status, error, message, headers);
+        }
+
+        if (status === 401) {
+            return new AuthenticationError(status, error, message, headers);
+        }
+
+        if (status === 403) {
+            return new PermissionDeniedError(status, error, message, headers);
+        }
+
+        if (status === 404) {
+            return new NotFoundError(status, error, message, headers);
+        }
+
+        if (status === 409) {
+            return new ConflictError(status, error, message, headers);
+        }
+
+        if (status === 422) {
+            return new UnprocessableEntityError(status, error, message, headers);
+        }
+
+        if (status === 429) {
+            return new RateLimitError(status, error, message, headers);
+        }
+
+        if (status >= 500) {
+            return new InternalServerError(status, error, message, headers);
+        }
+
+        return new APIError(status, error, message, headers);
+    }
+}
+
+export class APIUserAbortError extends APIError {
+    override readonly status: undefined = undefined;
+
+    constructor({ message }: { message?: string } = {}) {
+        super(undefined, undefined, message || 'Request was aborted.', undefined);
+    }
+}
+
+export class APIConnectionError extends APIError {
+    override readonly status: undefined = undefined;
+
+    constructor({ message, cause }: { message?: string | undefined; cause?: Error | undefined }) {
+        super(undefined, undefined, message || 'Connection error.', undefined);
+        // in some environments the 'cause' property is already declared
+        // @ts-ignore
+        if (cause) this.cause = cause;
+    }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+    constructor({ message }: { message?: string } = {}) {
+        super({ message: message ?? 'Request timed out.' });
+    }
+}
+
+export class BadRequestError extends APIError {
+    override readonly status = 400 as const;
+}
+
+export class AuthenticationError extends APIError {
+    override readonly status = 401 as const;
+}
+
+export class PermissionDeniedError extends APIError {
+    override readonly status = 403 as const;
+}
+
+export class NotFoundError extends APIError {
+    override readonly status = 404 as const;
+}
+
+export class ConflictError extends APIError {
+    override readonly status = 409 as const;
+}
+
+export class UnprocessableEntityError extends APIError {
+    override readonly status = 422 as const;
+}
+
+export class RateLimitError extends APIError {
+    override readonly status = 429 as const;
+}
+
+export class InternalServerError extends APIError {}

package/dist/src/index.ts

@@ -0,0 +1,210 @@
+import * as Errors from './error';
+import { type Agent } from './_shims/index';
+import * as Core from './core';
+import * as API from './resources/index';
+
+export interface ClientOptions {
+    /**
+     * Defaults to process.env['SPACEDF_ORG_ID'].
+     */
+    organization?: string | null | undefined;
+    /**
+     * Defaults to process.env['SPACEDF_API_KEY'].
+     */
+    APIKey?: string | undefined;
+    /**
+     * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+     *
+     * Defaults to process.env['SPACEDF_SDK_BASE_URL'].
+     */
+    baseURL?: string | null | undefined;
+
+    /**
+     * The maximum amount of time (in milliseconds) that the client should wait for a response
+     * from the server before timing out a single request.
+     *
+     * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+     * much longer than this timeout before the promise succeeds or fails.
+     */
+    timeout?: number;
+
+    /**
+     * An HTTP agent used to manage HTTP(S) connections.
+     *
+     * If not provided, an agent will be constructed by default in the Node.js environment,
+     * otherwise no agent is used.
+     */
+    httpAgent?: Agent;
+
+    /**
+     * Specify a custom `fetch` function implementation.
+     *
+     * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+     * defined globally.
+     */
+    fetch?: Core.Fetch | undefined;
+
+    /**
+     * The maximum number of times that the client will retry a request in case of a
+     * temporary failure, like a network error or a 5XX error from the server.
+     *
+     * @default 2
+     */
+    maxRetries?: number;
+
+    /**
+     * Default headers to include with every request to the API.
+     *
+     * These can be removed in individual requests by explicitly setting the
+     * header to `undefined` or `null` in request options.
+     */
+    defaultHeaders?: Core.Headers;
+
+    /**
+     * Default query parameters to include with every request to the API.
+     *
+     * These can be removed in individual requests by explicitly setting the
+     * param to `undefined` in request options.
+     */
+    defaultQuery?: Core.DefaultQuery;
+
+    /**
+     * By default, only use one instance per organization. If you want to use multiple organizations, use them on the server side.
+     *
+     * @default false
+     */
+    allowMultiOrgs?: boolean;
+}
+
+/**
+ * API Client for interfacing with the SpaceDF SDK API.
+ */
+export class SpaceDFSDK extends Core.APIClient {
+    organization: string | null;
+    accessToken: string | null | undefined;
+
+    private _options: ClientOptions;
+
+    /**
+     * API Client for interfacing with the Spacedf SDK API.
+     *
+     * @param {string | null | undefined} [opts.organization=process.env['SPACEDF_ORG_ID'] ?? null]
+     * @param {string | undefined} [opts.APIKey=process.env['SPACEDF_API_KEY']]
+     * @param {string} [opts.baseURL=process.env['SPACEDF_SDK_BASE_URL'] ?? https://api.v0.spacedf.net/] - Override the default base URL for the API.
+     * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
+     * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+     * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+     * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+     * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+     * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+     * @param {boolean} [opts.allowMultiOrgs=false] - Only set this option to `true` if you handle it on the server side or using multiple organizations.
+     */
+    constructor({
+        baseURL = Core.readEnv('SPACEDF_SDK_BASE_URL'),
+        organization = Core.readEnv('SPACEDF_ORG_ID') ?? null,
+        APIKey = Core.readEnv('SPACEDF_API_KEY'),
+        allowMultiOrgs = false,
+        ...opts
+    }: ClientOptions = {}) {
+        if (!allowMultiOrgs) {
+            if (baseURL && organization)
+                throw new Errors.SpaceDFError('`baseURL` will be overridden by `organization`. You should only configure a single property.');
+
+            if (organization) {
+                baseURL = `https://${organization}.api.v0.spacedf.net/api`;
+            }
+        }
+
+        const options: ClientOptions = {
+            organization,
+            APIKey,
+            baseURL: baseURL || `https://api.v0.spacedf.net/api`,
+            ...opts,
+        };
+
+        super({
+            APIKey: options.APIKey,
+            baseURL: options.baseURL!,
+            timeout: options.timeout ?? 60 * 1000 /* 1 minute */,
+            httpAgent: options.httpAgent,
+            maxRetries: options.maxRetries,
+            allowMultiOrgs,
+            fetch: options.fetch,
+        });
+
+        this._options = options;
+        this.APIKey = APIKey;
+        this.organization = organization;
+    }
+
+    auth: API.Auth = new API.Auth(this);
+    spacePolicies: API.SpacePolicies = new API.SpacePolicies(this);
+    spaceRoleUsers: API.SpaceRoleUsers = new API.SpaceRoleUsers(this);
+    spaceRoles: API.SpaceRoles = new API.SpaceRoles(this);
+    spaces: API.Spaces = new API.Spaces(this);
+    dashboards: API.Dashboards = new API.Dashboards(this);
+    deviceStates: API.DeviceStates = new API.DeviceStates(this);
+    oauth2: API.OAuth2 = new API.OAuth2(this);
+    credentials: API.Credentials = new API.Credentials(this);
+    users: API.Users = new API.Users(this);
+    invitation: API.Invitation = new API.Invitation(this);
+    joinSpace: API.JoinSpace = new API.JoinSpace(this);
+    presignedUrl: API.PresignedUrl = new API.PresignedUrl(this);
+
+    protected override defaultQuery(): Core.DefaultQuery | undefined {
+        return this._options.defaultQuery;
+    }
+
+    protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+        return {
+            ...super.defaultHeaders(opts),
+            ...this._options.defaultHeaders,
+        };
+    }
+
+    protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+        const Authorization = `Bearer ${(this.allowMultiOrgs && opts.accessToken) || this.accessToken || ''}`;
+        const APIKey = (this.allowMultiOrgs && opts.APIKey) || this.APIKey;
+
+        return { Authorization, 'x-api-key': APIKey };
+    }
+
+    public setAccessToken(token: string | null): void {
+        this.accessToken = token;
+    }
+
+    static SpaceDFSDK = this;
+    static DEFAULT_TIMEOUT = 60 * 1000; // 1 minute
+
+    static SpaceDFError = Errors.SpaceDFError;
+    static APIError = Errors.APIError;
+    static APIConnectionError = Errors.APIConnectionError;
+    static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+    static APIUserAbortError = Errors.APIUserAbortError;
+    static NotFoundError = Errors.NotFoundError;
+    static ConflictError = Errors.ConflictError;
+    static RateLimitError = Errors.RateLimitError;
+    static BadRequestError = Errors.BadRequestError;
+    static AuthenticationError = Errors.AuthenticationError;
+    static InternalServerError = Errors.InternalServerError;
+    static PermissionDeniedError = Errors.PermissionDeniedError;
+    static UnprocessableEntityError = Errors.UnprocessableEntityError;
+}
+
+export const {
+    SpaceDFError,
+    APIError,
+    APIConnectionError,
+    APIConnectionTimeoutError,
+    APIUserAbortError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    BadRequestError,
+    AuthenticationError,
+    InternalServerError,
+    PermissionDeniedError,
+    UnprocessableEntityError,
+} = Errors;
+
+export default SpaceDFSDK;

package/dist/src/libs/utils.ts

@@ -0,0 +1,66 @@
+import { SpaceDFError } from '../error';
+import { createHash } from 'node:crypto';
+
+/**
+ * Converts a given string to its Base64 encoded representation.
+ *
+ * @param {string | null | undefined} str - The input string to be encoded in Base64. If the input is `null` or `undefined`, an empty string is returned.
+ *
+ * @returns {string} - The Base64 encoded string. If the input is invalid (null or undefined), an empty string is returned.
+ *
+ * This function works in both Node.js and browser environments:
+ * - In **Node.js**, it uses `Buffer.from()` to convert the string into Base64.
+ * - In **browser environments**, it uses the `btoa()` function to generate the Base64 encoded string.
+ *
+ * If neither `Buffer` (Node.js) nor `btoa` (browser) are available, it throws a custom `SpaceDFError`.
+ *
+ * @throws {SpaceDFError} - Throws an error if neither `Buffer` nor `btoa` are available for Base64 encoding.
+ */
+export const toBase64 = (str: string | null | undefined): string => {
+    if (!str) return '';
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(str).toString('base64');
+    }
+
+    if (typeof btoa !== 'undefined') {
+        return btoa(str);
+    }
+
+    throw new SpaceDFError('Cannot generate b64 string; Expected `Buffer` or `btoa` to be defined');
+};
+
+/**
+ * Generates a SHA-256 hash for the provided data, compatible with both Node.js and browser environments.
+ *
+ * @param data - The data to hash, either as a string or a binary-like object.
+ * @returns A promise that resolves to the SHA-256 hash as an ArrayBuffer (in browser) or Buffer (in Node.js).
+ */
+export const toSHA256 = async (data: string | NodeJS.ArrayBufferView) => {
+    const encodedData = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+
+    // @ts-ignore
+    if (typeof globalThis !== 'undefined' && typeof globalThis.crypto !== 'undefined') {
+        // @ts-ignore
+        const hash = await globalThis.crypto.subtle.digest('SHA-256', encodedData);
+        return hash;
+    }
+
+    return createHash('sha256').update(encodedData).digest();
+};
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+    return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+/**
+ * https://stackoverflow.com/a/2117523
+ */
+export const uuid4 = () => {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+};
+
+export const rstripBase64 = (base64: string) => base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

package/dist/src/resource.ts

@@ -0,0 +1,9 @@
+import type { SpaceDFSDK } from './index';
+
+export class APIResource {
+    protected _client: SpaceDFSDK;
+
+    constructor(client: SpaceDFSDK) {
+        this._client = client;
+    }
+}

package/dist/src/resources/auth/auth.ts

@@ -0,0 +1,102 @@
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class Auth extends APIResource {
+    login(body: AuthLoginParams, options?: Core.RequestOptions): Core.APIPromise<AuthTokenPair> {
+        return this._client.post(`/auth/login`, { body, ...options });
+    }
+
+    oauth2Google(body: OAuthLogin, options?: Core.RequestOptions): Core.APIPromise<OAuthLogin> {
+        return this._client.post(`/auth/oauth2/google`, { body, ...options });
+    }
+
+    oauthSendOtp(body: OAuthSendOtp, options?: Core.RequestOptions): Core.APIPromise<OAuthSendOtp> {
+        return this._client.post(`/auth/send-otp`, { body, ...options });
+    }
+
+    oauth2SpaceDF(body: OAuthSpaceDF, options?: Core.RequestOptions): Core.APIPromise<OAuthSpaceDF> {
+        return this._client.post(`/auth/oauth2/spacedf-console`, { body, ...options });
+    }
+
+    refreshToken(body: AuthRefreshTokenParams, options?: Core.RequestOptions): Core.APIPromise<CustomTokenRefresh> {
+        return this._client.post(`/auth/refresh-token`, { body, ...options });
+    }
+
+    register(body: AuthRegisterParams, options?: Core.RequestOptions): Core.APIPromise<Registration> {
+        return this._client.post(`/auth/register`, { body, ...options });
+    }
+
+    switchSpaces(body: AuthRefreshTokenParams, options?: Core.RequestOptions): Core.APIPromise<CustomTokenRefresh> {
+        return this._client.post(`/auth/spaces/switch`, { body, ...options });
+    }
+}
+
+export interface AuthTokenPair {
+    refresh: string;
+
+    access: string;
+
+    default_space: string;
+}
+
+export interface CustomTokenRefresh {
+    refresh: string;
+
+    access?: string;
+
+    space?: string;
+}
+
+export interface OAuthLogin {
+    authorization_code: string;
+
+    code_verifier: string;
+}
+
+export interface OAuthSendOtp {
+    email: string;
+}
+
+export interface OAuthSpaceDF {
+    code_verifier: string;
+
+    code: string;
+
+    client_id: string;
+}
+
+export interface Registration {
+    id?: number;
+
+    first_name: string;
+
+    last_name: string;
+
+    email: string;
+
+    default_space?: string;
+}
+
+export interface AuthLoginParams {
+    email: string;
+
+    password: string;
+}
+
+export interface AuthRefreshTokenParams {
+    refresh: string;
+
+    space: string;
+}
+
+export interface AuthRegisterParams {
+    email: string;
+
+    password: string;
+
+    first_name: string;
+
+    last_name: string;
+
+    otp: string;
+}

package/dist/src/resources/auth/credentials.ts

@@ -0,0 +1,12 @@
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class Credentials extends APIResource {
+    retrieve(options?: Core.RequestOptions): Core.APIPromise<OAuthCredentials> {
+        return this._client.get(`/credentials`, options);
+    }
+}
+
+export interface OAuthCredentials {
+    client_id: string;
+}

package/dist/src/resources/auth/index.ts

@@ -0,0 +1,10 @@
+export * from './auth';
+export * from './spaces';
+export * from './space-policies';
+export * from './space-roles';
+export * from './space-role-users';
+export * from './credentials';
+export * from './users';
+export * from './invitation';
+export * from './join-space';
+export * from './presigned-url';

package/dist/src/resources/auth/invitation.ts

@@ -0,0 +1,17 @@
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class Invitation extends APIResource {
+    create(id: number, body: OAuthInvitation, options?: Core.RequestOptions): Core.APIPromise<OAuthInvitation> {
+        return this._client.post(`/invitation/${id}`, { body, ...options });
+    }
+}
+
+export interface OAuthInvitation {
+    receiver_list: Receiver[];
+}
+
+export interface Receiver {
+    email: string;
+    space_role_id: string;
+}

package/dist/src/resources/auth/join-space.ts

@@ -0,0 +1,8 @@
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class JoinSpace extends APIResource {
+    get(token: string, options?: Core.RequestOptions): Core.APIPromise<void> {
+        return this._client.get(`/join-space/${token}`, options);
+    }
+}

package/dist/src/resources/auth/presigned-url.ts

@@ -0,0 +1,13 @@
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class PresignedUrl extends APIResource {
+    get(options?: Core.RequestOptions): Core.APIPromise<PresignedUrlResponse> {
+        return this._client.get('/presigned-url', options);
+    }
+}
+
+export interface PresignedUrlResponse {
+    presigned_url: string;
+    file_name: string;
+}

package/dist/src/resources/auth/space-policies.ts

@@ -0,0 +1,55 @@
+import { APIResource } from '../../resource';
+import { isRequestOptions } from '../../core';
+import { ListParamsResponse, ListResponse } from '../../types/api';
+import * as Core from '../../core';
+
+export class SpacePolicies extends APIResource {
+    retrieve(id: number, options?: Core.RequestOptions): Core.APIPromise<SpacePolicy> {
+        return this._client.get(`/space-policies/${id}`, options);
+    }
+
+    list(query?: SpacePolicyListParams, options?: Core.RequestOptions): Core.APIPromise<SpacePolicyListResponse>;
+    list(options?: Core.RequestOptions): Core.APIPromise<SpacePolicyListResponse>;
+    list(query: SpacePolicyListParams | Core.RequestOptions = {}, options?: Core.RequestOptions): Core.APIPromise<SpacePolicyListResponse> {
+        if (isRequestOptions(query)) {
+            return this.list({}, query);
+        }
+        return this._client.get(`/space-policies`, { query, ...options });
+    }
+}
+
+export interface SpacePolicy {
+    description: string;
+
+    name: string;
+
+    permissions: Array<
+        | 'UPDATE_SPACE'
+        | 'DELETE_SPACE'
+        | 'READ_SPACE_ROLE'
+        | 'CREATE_SPACE_ROLE'
+        | 'UPDATE_SPACE_ROLE'
+        | 'DELETE_SPACE_ROLE'
+        | 'READ_SPACE_MEMBER'
+        | 'INVITE_SPACE_MEMBER'
+        | 'UPDATE_SPACE_MEMBER_ROLE'
+        | 'REMOVE_SPACE_MEMBER'
+        | 'READ_DASHBOARD'
+        | 'CREATE_DASHBOARD'
+        | 'UPDATE_DASHBOARD'
+        | 'DELETE_DASHBOARD'
+        | 'READ_DEVICE_STATE'
+    >;
+
+    tags: Array<string>;
+
+    id?: number;
+
+    readonly created_at?: string;
+
+    readonly updated_at?: string;
+}
+
+export type SpacePolicyListResponse = ListResponse<SpacePolicy>;
+
+export type SpacePolicyListParams = ListParamsResponse;