@hypericon/surf-client

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);