@hypericon/surf-client
v0.3.0
Published
List, download, and create product releases to/from [Surf](https://surf.hypericon.co.uk).
Downloads
14
Readme
Surf Client
List, download, and create product releases to/from Surf.
See also: https://github.com/hypcn/surf
Install
Node.js only, not intended for browser use.
$ npm i @hypericon/surf-client
Types are included
CLI
A development CLI is included to list, create, and download releases.
A product ID and an API key must be supplied, either as CLI arguments or as environment variables. CLI arguments take precedence.
- Product ID: either
SURF_PRODUCT=<the-product-id>
or--product=<the-product-id>
- API key: either
SURF_API_KEY=<the-api-key>
or--apiKey=<the-api-key>
# List releases for the product
npx surf list
# Create a new release for the product. The new version identifier is added in a prompt during the release
npx surf upload [...files/folders]
# Example:
npx surf upload dist package.json docs README.md
# Download a release, or download the latest if no release is specified
npx surf download [--release=<optional-release-id>]
Usage
Either use raw functions, or create a client object to manage common parameters.
Using functions:
import { getReleases, downloadRelease, Release } from "@hypericon/surf-client";
import AdmZip from "adm-zip";
import { join } from "path";
import { mkdir } from "fs/promises";
const releases: Release[] = await getReleases({
productId: "<the-surf-product-id>",
apiKey: "<the-surf-api-key>",
surfOrigin?: "http://localhost:3000", // default: "https://surf.hypericon.co.uk"
logger?: SimpleLogger, // An Axe logger instance (https://www.npmjs.com/package/@hypericon/axe)
});
const releaseToDownload: Release = releases[0];
const zipBuffer: Buffer = await downloadRelease(releaseToDownload.id, {
productId: "<the-surf-product-id>",
apiKey: "<the-surf-api-key>",
surfOrigin?: "http://localhost:3000", // default: "https://surf.hypericon.co.uk"
logger?: SimpleLogger, // An Axe logger instance (https://www.npmjs.com/package/@hypericon/axe)
});
// Unpacking the .zip will depend on the application.
// For example:
const zip = new AdmZip(zipBuffer);
const outputDir = join(process.cwd(), ".temp");
await mkdir(outputDir, { recursive: true });
for (const entry of entries) {
if (entry.entryName === "package.json") zip.extractEntryTo(entry, outputDir);
else if (entry.entryName.startsWith("dist/")) zip.extractEntryTo(entry, outputDir);
else console.log(`Ignoring entry: ${entry.entryName}`);
}
console.log(`Extracted ${zip.getEntries().length} entries to ${outputDir}`);
Using the class:
import { SurfClient, Release } from "@hypericon/surf-client";
const surf = new SurfClient({
apiKey: "<the-surf-api-key>",
surfOrigin?: "http://localhost:3000", // default: "https://surf.hypericon.co.uk"
logger?: true, // true | Logger | undefined,
});
const releases: Release[] = await surf.getReleases("<the-surf-product-id>");
const release: Release = releases[0];
const zipFile: Buffer = await surf.downloadRelease("<the-surf-product-id>", release.id);
// as above for unpacking the .zip
Creating Releases
import { createRelease, getBundleContentsTable, NewReleaseInfo } from "../src";
import AdmZip from "adm-zip";
const PRODUCT_ID = "<the-surf-product-id>";
const API_KEY = "<the-surf-api-key>"; // with `canUpload` flag enabled
const NEW_VERSION = "1.2.3"; // The new version, can be any string that can also be a file name
// Create example zip containing:
// /package.json
// /dist/...
// /docs/README.md
const zip = new AdmZip();
zip.addLocalFile(join(process.cwd(), "package.json"));
await zip.addLocalFolderPromise(join(process.cwd(), "dist"), { zipPath: "dist" }); // note the `zipPath`
zip.addLocalFile(join(process.cwd(), "README.md"), "docs");
let technicalInfo = `## Bundle Contents\n\n`;
technicalInfo += getBundleContentsTable(zip); // build a markdown table of file names and sizes
const release: NewReleaseInfo = {
version: NEW_VERSION,
releaseNotes?: "Any release notes or other information",
technicalInfo?: technicalInfo,
isPrerelease?: boolean, // default `true`
isArchived?: boolean, // default `false`
};
const file: Buffer = await zip.toBufferPromise();
const { created, url } = await createRelease(release, file, {
apiKey: API_KEY,
productId: PRODUCT_ID,
surfOrigin: SURF_ORIGIN,
});
console.log("Created release:", created);
console.log("View and edit release:", url);