balena-sdk
Version:
The Balena JavaScript SDK
491 lines (490 loc) • 26.2 kB
TypeScript
import type { InjectedDependenciesParam, InjectedOptionsParam } from '..';
import type { ReleaseTag, Release, User, Image } from '../types/models';
import type { BuilderUrlDeployOptions } from '../util/builder';
import type { ODataOptionsWithoutCount, OptionsToResponse } from 'pinejs-client-core';
export interface ReleaseRawVersionApplicationPair {
application: string | number;
rawVersion: string;
}
type ReleaseRead = Release['Read'];
export interface ReleaseWithImageDetails extends ReleaseRead {
images: Array<{
id: number;
service_name: string;
}>;
user: Pick<User['Read'], 'id' | 'username'> | undefined;
}
declare const getReleaseModel: (deps: InjectedDependenciesParam, opts: InjectedOptionsParam) => {
get: <T extends ODataOptionsWithoutCount<Release["Read"]>>(commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, options?: T) => Promise<OptionsToResponse<Release["Read"], T, undefined>[number]>;
getAllByApplication: <T extends ODataOptionsWithoutCount<Release["Read"]>>(slugOrUuidOrId: string | number, options?: T) => Promise<NoInfer<OptionsToResponse<{
created_at: import("@balena/sbvr-types").Types["Date Time"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
belongs_to__application: {
__id: import("..").Application["Read"]["id"];
} | [import("..").Application["Read"]];
commit: import("@balena/sbvr-types").Types["Short Text"]["Read"];
composition: import("@balena/sbvr-types").Types["JSON"]["Read"];
status: import("@balena/sbvr-types").Types["Short Text"]["Read"];
source: import("@balena/sbvr-types").Types["Short Text"]["Read"];
build_log: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
is_invalidated: import("@balena/sbvr-types").Types["Boolean"]["Read"];
start_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"];
end_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"] | null;
update_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"];
release_version: import("@balena/sbvr-types").Types["Short Text"]["Read"] | null;
contract: import("@balena/sbvr-types").Types["JSON"]["Read"] | null;
is_passing_tests: import("@balena/sbvr-types").Types["Boolean"]["Read"];
is_finalized_at__date: import("@balena/sbvr-types").Types["Date Time"]["Read"] | null;
phase: "next" | "current" | "sunset" | "end-of-life" | null;
is_final: import("@balena/sbvr-types").Types["Boolean"]["Read"];
semver: import("@balena/sbvr-types").Types["Short Text"]["Read"];
semver_major: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_minor: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_patch: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_prerelease: import("@balena/sbvr-types").Types["Short Text"]["Read"];
semver_build: import("@balena/sbvr-types").Types["Short Text"]["Read"];
variant: import("@balena/sbvr-types").Types["Short Text"]["Read"];
revision: import("@balena/sbvr-types").Types["Integer"]["Read"] | null;
raw_version: import("@balena/sbvr-types").Types["Short Text"]["Read"];
version: import("@balena/sbvr-types").Types["JSON"]["Read"];
known_issue_list: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
note: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
invalidation_reason: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
is_created_by__user: {
__id: User["Read"]["id"];
} | [User["Read"]] | [] | null;
release__has__tag_key?: Array<ReleaseTag["Read"]>;
release_tag?: Array<ReleaseTag["Read"]>;
release__has__asset_key?: Array<import("..").ReleaseAsset["Read"]>;
release_asset?: Array<import("..").ReleaseAsset["Read"]>;
image__is_part_of__release?: Array<import("..").ImageIsPartOfRelease["Read"]>;
release_image?: Array<import("..").ImageIsPartOfRelease["Read"]>;
contains__image?: Array<import("..").ImageIsPartOfRelease["Read"]>;
should_be_running_on__application?: Array<import("..").Application["Read"]>;
should_be_running_on__device?: Array<import("..").Device["Read"]>;
is_running_on__device?: Array<import("..").Device["Read"]>;
is_pinned_to__device?: Array<import("..").Device["Read"]>;
should_operate__device?: Array<import("..").Device["Read"]>;
should_manage__device?: Array<import("..").Device["Read"]>;
provides__device__installs__image?: Array<import("..").ImageInstall["Read"]>;
provides__image_install?: Array<import("..").ImageInstall["Read"]>;
}, NonNullable<T>, undefined>>>;
getLatestByApplication: <T extends ODataOptionsWithoutCount<Release["Read"]>>(slugOrUuidOrId: string | number, options?: T) => Promise<import("pinejs-client-core/node_modules/@balena/abstract-sql-to-typescript", { with: { "resolution-mode": "import" } }).PickDeferred<{
created_at: import("@balena/sbvr-types").Types["Date Time"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
belongs_to__application: {
__id: import("..").Application["Read"]["id"];
} | [import("..").Application["Read"]];
commit: import("@balena/sbvr-types").Types["Short Text"]["Read"];
composition: import("@balena/sbvr-types").Types["JSON"]["Read"];
status: import("@balena/sbvr-types").Types["Short Text"]["Read"];
source: import("@balena/sbvr-types").Types["Short Text"]["Read"];
build_log: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
is_invalidated: import("@balena/sbvr-types").Types["Boolean"]["Read"];
start_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"];
end_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"] | null;
update_timestamp: import("@balena/sbvr-types").Types["Date Time"]["Read"];
release_version: import("@balena/sbvr-types").Types["Short Text"]["Read"] | null;
contract: import("@balena/sbvr-types").Types["JSON"]["Read"] | null;
is_passing_tests: import("@balena/sbvr-types").Types["Boolean"]["Read"];
is_finalized_at__date: import("@balena/sbvr-types").Types["Date Time"]["Read"] | null;
phase: "next" | "current" | "sunset" | "end-of-life" | null;
is_final: import("@balena/sbvr-types").Types["Boolean"]["Read"];
semver: import("@balena/sbvr-types").Types["Short Text"]["Read"];
semver_major: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_minor: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_patch: import("@balena/sbvr-types").Types["Integer"]["Read"];
semver_prerelease: import("@balena/sbvr-types").Types["Short Text"]["Read"];
semver_build: import("@balena/sbvr-types").Types["Short Text"]["Read"];
variant: import("@balena/sbvr-types").Types["Short Text"]["Read"];
revision: import("@balena/sbvr-types").Types["Integer"]["Read"] | null;
raw_version: import("@balena/sbvr-types").Types["Short Text"]["Read"];
version: import("@balena/sbvr-types").Types["JSON"]["Read"];
known_issue_list: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
note: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
invalidation_reason: import("@balena/sbvr-types").Types["Text"]["Read"] | null;
is_created_by__user: {
__id: User["Read"]["id"];
} | [User["Read"]] | [] | null;
release__has__tag_key?: Array<ReleaseTag["Read"]>;
release_tag?: Array<ReleaseTag["Read"]>;
release__has__asset_key?: Array<import("..").ReleaseAsset["Read"]>;
release_asset?: Array<import("..").ReleaseAsset["Read"]>;
image__is_part_of__release?: Array<import("..").ImageIsPartOfRelease["Read"]>;
release_image?: Array<import("..").ImageIsPartOfRelease["Read"]>;
contains__image?: Array<import("..").ImageIsPartOfRelease["Read"]>;
should_be_running_on__application?: Array<import("..").Application["Read"]>;
should_be_running_on__device?: Array<import("..").Device["Read"]>;
is_running_on__device?: Array<import("..").Device["Read"]>;
is_pinned_to__device?: Array<import("..").Device["Read"]>;
should_operate__device?: Array<import("..").Device["Read"]>;
should_manage__device?: Array<import("..").Device["Read"]>;
provides__device__installs__image?: Array<import("..").ImageInstall["Read"]>;
provides__image_install?: Array<import("..").ImageInstall["Read"]>;
}, "variant" | "id" | "source" | "status" | "created_at" | "is_created_by__user" | "note" | "contract" | "end_timestamp" | "belongs_to__application" | "commit" | "composition" | "build_log" | "is_invalidated" | "start_timestamp" | "update_timestamp" | "release_version" | "is_passing_tests" | "is_finalized_at__date" | "phase" | "is_final" | "semver" | "semver_major" | "semver_minor" | "semver_patch" | "semver_prerelease" | "semver_build" | "revision" | "raw_version" | "version" | "known_issue_list" | "invalidation_reason" | "release__has__tag_key" | "release_tag" | "release__has__asset_key" | "release_asset" | "image__is_part_of__release" | "release_image" | "contains__image" | "should_be_running_on__application" | "should_be_running_on__device" | "is_running_on__device" | "is_pinned_to__device" | "should_operate__device" | "should_manage__device" | "provides__device__installs__image" | "provides__image_install">>;
getWithImageDetails: <R extends ODataOptionsWithoutCount<Release["Read"]>, I extends ODataOptionsWithoutCount<Image["Read"]>>(commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, options?: {
release?: R;
image?: I;
}) => Promise<ReleaseWithImageDetails>;
createFromUrl: (slugOrUuidOrId: string | number, urlDeployOptions: BuilderUrlDeployOptions) => Promise<number>;
finalize: (commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair) => Promise<void>;
setIsInvalidated: (commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, isInvalidated: boolean) => Promise<void>;
setNote: (commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, noteOrNull: string | null) => Promise<void>;
setKnownIssueList: (commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, knownIssueListOrNull: string | null) => Promise<void>;
tags: {
/**
* @summary Get all release tags for an application
* @name getAllByApplication
* @public
* @function
* @memberof balena.models.release.tags
*
* @param {String|Number} slugOrUuidOrId - application slug (string), uuid (string) or id (number)
* @param {Object} [options={}] - extra pine options to use
* @fulfil {Object[]} - release tags
* @returns {Promise}
*
* @example
* balena.models.release.tags.getAllByApplication('myorganization/myapp').then(function(tags) {
* console.log(tags);
* });
*
* @example
* balena.models.release.tags.getAllByApplication(999999).then(function(tags) {
* console.log(tags);
* });
*/
getAllByApplication<T extends ODataOptionsWithoutCount<ReleaseTag["Read"]>>(slugOrUuidOrId: string | number, options?: T): Promise<NoInfer<import("pinejs-client-core/node_modules/@balena/abstract-sql-to-typescript", { with: { "resolution-mode": "import" } }).PickDeferred<{
release: {
__id: Release["Read"]["id"];
} | [Release["Read"]];
tag_key: import("@balena/sbvr-types").Types["Short Text"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
value: import("@balena/sbvr-types").Types["Text"]["Read"];
}, "release" | "id" | "value" | "tag_key">[]>>;
/**
* @summary Get all release tags for a release
* @name getAllByRelease
* @public
* @function
* @memberof balena.models.release.tags
*
* @param {String|Number|Object} commitOrIdOrRawVersion - release commit (string) or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string) pair of the release
* @param {Object} [options={}] - extra pine options to use
* @fulfil {Object[]} - release tags
* @returns {Promise}
*
* @example
* balena.models.release.tags.getAllByRelease(123).then(function(tags) {
* console.log(tags);
* });
*
* @example
* balena.models.release.tags.getAllByRelease('7cf02a6').then(function(tags) {
* console.log(tags);
* });
*
* @example
* balena.models.release.tags.getAllByRelease({application: 456, rawVersion: '0.0.0'}).then(function(tags) {
* console.log(tags);
* });
*/
getAllByRelease<T extends ODataOptionsWithoutCount<ReleaseTag["Read"]>>(commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, options?: T): Promise<OptionsToResponse<{
release: {
__id: Release["Read"]["id"];
} | [Release["Read"]];
tag_key: import("@balena/sbvr-types").Types["Short Text"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
value: import("@balena/sbvr-types").Types["Text"]["Read"];
}, import("../util").MergePineOptions<import("../util").AliasResourceRead, {
$orderby: {
tag_key: "asc";
};
}, T>, undefined>>;
/**
* @summary Set a release tag
* @name set
* @public
* @function
* @memberof balena.models.release.tags
*
* @param {String|Number|Object} commitOrIdOrRawVersion - release commit (string) or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string) pair of the release
* @param {String} tagKey - tag key
* @param {String|undefined} value - tag value
*
* @returns {Promise}
*
* @example
* balena.models.release.tags.set(123, 'EDITOR', 'vim');
*
* @example
* balena.models.release.tags.set('7cf02a6', 'EDITOR', 'vim');
*
* @example
* balena.models.release.tags.set({application: 456, rawVersion: '0.0.0'}, 'EDITOR', 'vim');
*/
set: (parentParam: string | number | import("../../typings/utils").Dictionary<unknown>, key: string, value: string) => Promise<void>;
/**
* @summary Remove a release tag
* @name remove
* @public
* @function
* @memberof balena.models.release.tags
*
* @param {String|Number|Object} commitOrIdOrRawVersion - release commit (string) or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string) pair of the release
* @param {String} tagKey - tag key
* @returns {Promise}
*
* @example
* balena.models.release.tags.remove(123, 'EDITOR');
*
* @example
* balena.models.release.tags.remove('7cf02a6', 'EDITOR');
*
* @example
* balena.models.release.tags.remove({application: 456, rawVersion: '0.0.0'}, 'EDITOR');
*/
remove: (parentParam: string | number | import("../../typings/utils").Dictionary<unknown>, key: string) => Promise<void>;
};
asset: {
/**
* @summary Get all release assets for a release
* @name getAllByRelease
* @public
* @function
* @memberof balena.models.release.asset
*
* @param {String|Number|Object} commitOrIdOrRawVersion - release commit (string) or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string) pair of the release
* @param {Object} [options={}] - extra pine options to use
* @fulfil {Object[]} - release assets
* @returns {Promise}
*
* @example
* balena.models.release.asset.getAllByRelease(123).then(function(assets) {
* console.log(assets);
* });
*
* @example
* balena.models.release.asset.getAllByRelease('7cf02a6').then(function(assets) {
* console.log(assets);
* });
*
* @example
* balena.models.release.asset.getAllByRelease({ application: 456, raw_version: '1.2.3' }).then(function(assets) {
* console.log(assets);
* });
*/
getAllByRelease: <T extends ODataOptionsWithoutCount<import("..").ReleaseAsset["Read"]>>(commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair, options?: T) => Promise<OptionsToResponse<{
release: {
__id: Release["Read"]["id"];
} | [Release["Read"]];
asset_key: import("@balena/sbvr-types").Types["Short Text"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
asset: import("@balena/sbvr-types").Types["WebResource"]["Read"] | null;
}, import("../util").MergePineOptions<import("../util").AliasResourceRead, {
$orderby: {
id: "asc";
};
}, T>, undefined>>;
/**
* @summary Get a specific release asset
* @name get
* @public
* @function
* @memberof balena.models.release.asset
*
* @param {Number|Object} id - release asset ID or object specifying the unique release & asset_key pair
* @param {Object} [options={}] - extra pine options to use
* @fulfil {Object} - release asset
* @returns {Promise}
*
* @example
* balena.models.release.asset.get(123).then(function(asset) {
* console.log(asset);
* });
*
* @example
* balena.models.release.asset.get({
* asset_key: 'logo.png',
* release: 123
* }).then(function(asset) {
* console.log(asset);
* });
*/
get: <T extends ODataOptionsWithoutCount<import("..").ReleaseAsset["Read"]>>(id: number | {
asset_key: import("..").ReleaseAsset["Read"]["asset_key"];
release: string | number | ReleaseRawVersionApplicationPair;
}, options?: T) => Promise<NonNullable<OptionsToResponse<{
release: {
__id: Release["Read"]["id"];
} | [Release["Read"]];
asset_key: import("@balena/sbvr-types").Types["Short Text"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
asset: import("@balena/sbvr-types").Types["WebResource"]["Read"] | null;
}, T & {}, number | {
release: number;
asset_key: import("..").ReleaseAsset["Read"]["asset_key"];
}>>>;
/**
* @summary Download a release asset
* @name download
* @public
* @function
* @memberof balena.models.release.asset
*
* @param {Number|Object} id - release asset ID or object specifying the unique release & asset_key pair
* @fulfil {NodeJS.ReadableStream} - download stream
* @returns {Promise}
*
* @example
* balena.models.release.asset.download(123).then(function(stream) {
* stream.pipe(fs.createWriteStream('logo.png'));
* });
*
* @example
* balena.models.release.asset.download({
* asset_key: 'logo.png',
* release: 123
* }).then(function(stream) {
* stream.pipe(fs.createWriteStream('logo.png'));
* });
*/
download: (id: number | {
asset_key: import("..").ReleaseAsset["Read"]["asset_key"];
release: string | number | ReleaseRawVersionApplicationPair;
}) => Promise<import("balena-request").BalenaRequestStreamResult>;
/**
* @summary Upload a release asset
* @name upload
* @public
* @function
* @memberof balena.models.release.asset
*
* @param {Object} uploadParams - upload parameters
* @param {String|File} uploadParams.asset - asset file path (string, Node.js only) or File object (Node.js & browser). For File objects, use new File([content], filename, {type: mimeType})
* @param {String} uploadParams.asset_key - unique key for the asset within the release
* @param {Number} uploadParams.release - release ID
* @param {Object} [options={}] - upload options
* @param {Number} [options.chunkSize=5242880] - chunk size for multipart uploads (5MiB default)
* @param {Number} [options.parallelUploads=5] - number of parallel uploads for multipart
* @param {Boolean} [options.overwrite=false] - whether to overwrite existing asset
* @param {Function} [options.onUploadProgress] - callback for upload progress
* @fulfil {Object} - uploaded release asset
* @returns {Promise}
*
* @example
* // Upload from file path (Node.js)
* balena.models.release.asset.upload({
* asset: '/path/to/logo.png',
* asset_key: 'logo.png',
* release: 123
* }).then(function(asset) {
* console.log('Asset uploaded:', asset);
* });
*
* @example
* // Upload with File API (Node.js and browser)
* const content = Buffer.from('Hello, World!', 'utf-8');
* const file = new File([content], 'readme.txt', { type: 'text/plain' });
*
* balena.models.release.asset.upload({
* asset: file,
* asset_key: 'readme.txt',
* release: 123
* }).then(function(asset) {
* console.log('Asset uploaded:', asset);
* });
*
* @example
* // Upload large file with File API and progress tracking
* const largeContent = new Uint8Array(10 * 1024 * 1024); // 10MB
* const largeFile = new File([largeContent], 'data.bin', { type: 'application/octet-stream' });
*
* balena.models.release.asset.upload({
* asset: largeFile,
* asset_key: 'data.bin',
* release: 123
* }, {
* chunkSize: 5 * 1024 * 1024, // 5MB chunks
* parallelUploads: 3,
* onUploadProgress: function(progress) {
* const percent = (progress.uploaded / progress.total * 100).toFixed(2);
* console.log(`Upload progress: ${percent}%`);
* }
* }).then(function(asset) {
* console.log('Large file uploaded:', asset);
* });
*
* @example
* // Browser: Upload file from input element
* const fileInput = document.getElementById('fileInput');
* const file = fileInput.files[0]; // File object from input
*
* balena.models.release.asset.upload({
* asset: file,
* asset_key: file.name,
* release: 123
* }).then(function(asset) {
* console.log('File uploaded from browser:', asset);
* });
*
* @example
* // Upload with overwrite option
* balena.models.release.asset.upload({
* asset: '/path/to/logo.png',
* asset_key: 'logo.png',
* release: 123
* }, {
* overwrite: true
* }).then(function(asset) {
* console.log('Asset uploaded/updated:', asset);
* });
*/
upload: (uploadParams: Omit<{
release: import("@balena/sbvr-types").Types["Integer"]["Write"];
asset_key: import("@balena/sbvr-types").Types["Short Text"]["Write"];
asset: import("@balena/sbvr-types").Types["WebResource"]["Write"] | null;
}, "asset"> & {
asset: File | string;
}, { chunkSize, parallelUploads, overwrite, onUploadProgress, }?: {
chunkSize?: number | undefined;
parallelUploads?: number | undefined;
overwrite?: boolean | undefined;
onUploadProgress?: (progress: {
total: number;
uploaded: number;
}) => void | Promise<void>;
}) => Promise<import("pinejs-client-core/node_modules/@balena/abstract-sql-to-typescript", { with: { "resolution-mode": "import" } }).PickDeferred<{
release: {
__id: Release["Read"]["id"];
} | [Release["Read"]];
asset_key: import("@balena/sbvr-types").Types["Short Text"]["Read"];
id: import("@balena/sbvr-types").Types["Integer"]["Read"];
asset: import("@balena/sbvr-types").Types["WebResource"]["Read"] | null;
}, "release" | "id" | "asset_key" | "asset">>;
/**
* @summary Remove a release asset
* @name remove
* @public
* @function
* @memberof balena.models.release.asset
*
* @param {Number|Object} id - release asset ID or object specifying the unique release & asset_key pair
* @returns {Promise}
*
* @example
* balena.models.release.asset.remove(123);
*
* @example
* balena.models.release.asset.remove({
* asset_key: 'logo.png',
* release: 123
* });
*/
remove: (id: number | {
asset_key: import("..").ReleaseAsset["Read"]["asset_key"];
release: string | number | ReleaseRawVersionApplicationPair;
}) => Promise<void>;
};
};
export default getReleaseModel;