balena-sdk
Version:
The Balena JavaScript SDK
188 lines (187 loc) • 8.54 kB
TypeScript
import type { PineClient } from './pine';
import type { BalenaRequest, Interceptor } from 'balena-request';
export type { PineClient };
export type * as Pine from 'pinejs-client-core';
export * from './types/models';
export * from './types/jwt';
export * from './types/contract';
export * from './types/user-invite';
export * from './types/auth';
export type { Interceptor };
export type { ApplicationMembershipCreationOptions } from './models/application-membership';
export type { ApplicationInviteOptions } from './models/application-invite';
export type { AccountInfo, BankAccountBillingInfo, BillingAccountAddressInfo, BillingAddonPlanInfo, BillingInfo, BillingInfoType, BillingPlanBillingInfo, BillingPlanInfo, CardBillingInfo, InvoiceInfo, PlanChangeOptions, TokenBillingSubmitInfo, } from './models/billing';
export type { GaConfig, Config, ConfigVarDefinition, DeviceTypeJson, } from './models/config';
export type { DeviceState, DeviceMetrics, OverallStatus, SupervisorStatus, } from './models/device';
export type { ReleaseWithImageDetails } from './models/release';
export type { OrganizationInviteOptions } from './models/organization-invite';
export type { ImgConfigOptions, OsDownloadOptions, OsLines, OsTypes, OsUpdateVersions, OsVersion, } from './models/os';
export type { OsUpdateActionResult } from './util/device-actions/os-update';
export type { BuilderUrlDeployOptions } from './util/builder';
export type { CurrentService, DeviceWithServiceDetails, } from './util/device-service-details';
export type { BaseLog, ServiceLog, SystemLog, LogMessage, LogsSubscription, LogsOptions, } from './logs';
export interface InjectedDependenciesParam {
sdkInstance: BalenaSDK;
settings: {
get(key: string): string;
getAll(): {
[key: string]: string;
};
};
request: BalenaRequest;
auth: import('balena-auth').default;
pine: PineClient;
pubsub: import('./util/pubsub').PubSub;
}
export interface SdkOptions {
apiUrl?: string;
builderUrl?: string;
dashboardUrl?: string;
dataDirectory?: string | false;
isBrowser?: boolean;
debug?: boolean;
deviceUrlsBase?: string;
requestLimit?: number;
requestLimitInterval?: number;
retryRateLimitedRequests?: boolean | ((retryAfterMs: number) => boolean);
requestBatchingChunkSize?: number | {
numericId: number;
stringId: number;
};
}
export interface InjectedOptionsParam extends SdkOptions {
apiUrl: string;
apiVersion: string;
}
declare const sdkTemplate: {
auth(): (deps: InjectedDependenciesParam, opts: InjectedOptionsParam) => {
twoFactor: {
isEnabled: () => Promise<boolean>;
isPassed: () => Promise<boolean>;
getSetupKey: () => Promise<string>;
enable: (code: string) => Promise<string>;
verify: (code: string) => Promise<string>;
challenge: (code: string) => Promise<void>;
disable: (password: string) => Promise<string>;
};
whoami: () => Promise<import("./types/auth").WhoamiResult | undefined>;
authenticate: (credentials: {
email: string;
password: string;
}) => Promise<string>;
login: (credentials: {
email: string;
password: string;
}) => Promise<void>;
loginWithToken: (authToken: string) => Promise<void>;
isLoggedIn: () => Promise<boolean>;
getToken: () => Promise<string>;
getActorId: () => Promise<number>;
getUserInfo: () => Promise<import("./types/auth").UserInfo>;
logout: () => Promise<void>;
register: (credentials: {
email: string;
password: string;
"g-recaptcha-response"?: string;
}) => Promise<string>;
verifyEmail: (verificationPayload: {
email: string;
token: string;
}) => Promise<string>;
requestVerificationEmail: () => Promise<void>;
};
models(): typeof import("./models");
logs(): ({ request, sdkInstance, }: InjectedDependenciesParam, opts: InjectedOptionsParam) => {
subscribe(uuidOrId: string | number, options?: Pick<import("./logs").LogsOptions, "count"> | Required<import("./logs").LogsOptions>): Promise<import("./logs").LogsSubscription>;
history(uuidOrId: string | number, options?: import("./logs").LogsOptions): Promise<import("./logs").LogMessage[]>;
};
settings(): ({ settings }: InjectedDependenciesParam) => {
get: (key: string) => Promise<string>;
getAll: () => Promise<{
[key: string]: string;
}>;
};
};
export type BalenaSDK = {
[key in keyof typeof sdkTemplate]: ReturnType<ReturnType<(typeof sdkTemplate)[key]>>;
} & {
interceptors: Interceptor[];
request: BalenaRequest;
pine: PineClient;
utils: import('./util').BalenaUtils;
errors: typeof import('balena-errors');
version: string;
};
/**
* @namespace balena
*/
/**
* @module balena-sdk
*/
/**
* @summary Creates a new SDK instance using the default or the provided options.
*
* @description
* The module exports a single factory function.
*
* @example
* // with es6 imports
* import { getSdk } from 'balena-sdk';
* // or with node require
* const { getSdk } = require('balena-sdk');
*
* const balena = getSdk({
* apiUrl: "https://api.balena-cloud.com/",
* dataDirectory: "/opt/local/balena"
* });
*/
export declare const getSdk: ($opts?: SdkOptions) => BalenaSDK;
/**
* @summary Set shared default options
* @public
* @function
*
* @description
* Set options that are used by calls to `fromSharedOptions()`.
* The options accepted are the same as those used in the main SDK factory function.
* If you use this method, it should be called as soon as possible during app
* startup and before any calls to `fromSharedOptions()` are made.
*
* @param {Object} options - The shared default options
* @param {String} [options.apiUrl='https://api.balena-cloud.com/'] - the balena API url to use.
* @param {String} [options.builderUrl='https://builder.balena-cloud.com/'] - the balena builder url to use.
* @param {String} [options.deviceUrlsBase='balena-devices.com'] - the base balena device API url to use.
* @param {Number} [options.requestLimit] - the number of requests per requestLimitInterval that the SDK should respect.
* @param {Number} [options.requestLimitInterval = 60000] - the timespan that the requestLimit should apply to in milliseconds, defaults to 60000 (1 minute).
* @param {Boolean|Function} [options.retryRateLimitedRequests = false] - Determines whether to automatically retry requests that are failing with a 429 Too Many Requests status code and that include a numeric Retry-After response header.
* - If `false`, rate-limited requests will not be retried, and the rate limit error will be propagated.
* - If `true`, all rate-limited requests will be retried after the duration specified by the `Retry-After` header.
* - If a function `(retryAfterMs: number) => boolean` is provided, it will be called with the retry duration in ms and the request will be retried only when `true` is returned.
* @param {String|False} [options.dataDirectory='$HOME/.balena'] - *ignored in the browser unless false*, the directory where the user settings are stored, normally retrieved like `require('balena-settings-client').get('dataDirectory')`. Providing `false` creates an isolated in-memory instance.
* @param {Boolean} [options.isBrowser] - the flag to tell if the module works in the browser. If not set will be computed based on the presence of the global `window` value.
* @param {Boolean} [options.debug] - when set will print some extra debug information.
*
* @example
* import { setSharedOptions } from 'balena-sdk';
* setSharedOptions({
* apiUrl: 'https://api.balena-cloud.com/',
* builderUrl: 'https://builder.balena-cloud.com/',
* isBrowser: true,
* });
*/
export declare const setSharedOptions: (options: SdkOptions) => void;
/**
* @summary Create an SDK instance using shared default options
* @public
* @function
*
* @description
* Create an SDK instance using shared default options set using the `setSharedOptions()` method.
* If options have not been set using this method, then this method will use the
* same defaults as the main SDK factory function.
*
* @example
* import { fromSharedOptions } from 'balena-sdk';
* const sdk = fromSharedOptions();
*/
export declare const fromSharedOptions: () => BalenaSDK;