balena-sdk
Version:
The Balena JavaScript SDK
348 lines (347 loc) • 16 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<Release["Read"], T, undefined>>>;
getLatestByApplication: <T extends ODataOptionsWithoutCount<Release["Read"]>>(slugOrUuidOrId: string | number, options?: T) => Promise<OptionsToResponse<Release["Read"], T, undefined>[number]>;
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<OptionsToResponse<ReleaseTag["Read"], T, undefined>>;
/**
* @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('7cf02a69e4d34c9da573914963cf54fd').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<ReleaseTag["Read"], 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('7cf02a69e4d34c9da573914963cf54fd', 'EDITOR', 'vim');
*
* @example
* balena.models.release.tags.set({application: 456, rawVersion: '0.0.0'}, 'EDITOR', 'vim');
*/
set: (parentParam: string | number | Record<string, 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('7cf02a69e4d34c9da573914963cf54fd', 'EDITOR');
*
* @example
* balena.models.release.tags.remove({application: 456, rawVersion: '0.0.0'}, 'EDITOR');
*/
remove: (parentParam: string | number | Record<string, 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('7cf02a69e4d34c9da573914963cf54fd').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<import("..").ReleaseAsset["Read"], 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<OptionsToResponse<import("..").ReleaseAsset["Read"], T, undefined>[number]>;
/**
* @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;