@shard-for-obsidian/lib 0.2.0

package/README.md

@@ -0,0 +1,77 @@
+# shard-lib
+
+OCI-compatible container registry client library for TypeScript/JavaScript.
+
+## Features
+
+- Parse and validate Docker/OCI repository references
+- Interact with OCI registries (Docker Hub, GHCR, etc.)
+- Support for Docker v2 and OCI manifest formats
+- Bearer token and basic authentication
+- Link header parsing for pagination
+
+## Installation
+
+```bash
+pnpm add shard-lib
+```
+
+## Usage
+
+```typescript
+import { OciRegistryClient, parseRepoAndRef } from 'shard-lib';
+
+// Parse a repository reference
+const repo = parseRepoAndRef('ghcr.io/owner/repo:latest');
+console.log(repo.index.name); // 'ghcr.io'
+console.log(repo.tag); // 'latest'
+
+// Create a registry client
+const client = new OciRegistryClient({
+  repo: repo,
+  adapter: { fetch },
+  username: 'user',
+  password: 'token',
+});
+
+// List tags
+const tags = await client.listTags();
+
+// Get manifest
+const manifest = await client.getManifest('latest');
+```
+
+## Project Structure
+
+```
+src/
+  client/          # OCI registry client and adapters
+  errors/          # Custom error classes
+  ghcr/            # GitHub Container Registry constants
+  parsing/         # Repository and index parsing
+  types/           # TypeScript type definitions
+  utils/           # Utility functions
+  __tests__/       # Test files
+```
+
+## API
+
+### Parsing
+
+- `parseIndex(arg?: string): RegistryIndex` - Parse registry index/URL
+- `parseRepo(arg: string, defaultIndex?: string | RegistryIndex): RegistryRepo` - Parse repository
+- `parseRepoAndRef(arg: string, defaultIndex?: string | RegistryIndex): RegistryImage` - Parse repository with tag/digest
+- `urlFromIndex(index: RegistryIndex, scheme?: 'http' | 'https'): string` - Generate URL from index
+
+### Client
+
+- `OciRegistryClient` - Main registry client class
+  - `listTags()` - List repository tags
+  - `getManifest(ref: string)` - Get image manifest
+  - `getBlob(digest: string)` - Download blob by digest
+
+### Types
+
+See TypeScript definitions for complete type information.
+
+

package/dist/client/FetchAdapter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adapter interface for HTTP requests.
+ * Allows OciRegistryClient to work with different fetch implementations.
+ */
+export interface FetchAdapter {
+    /**
+     * Perform an HTTP request using fetch semantics.
+     * @param input URL string or Request object
+     * @param init Optional request initialization
+     * @returns Promise resolving to Response
+     */
+    fetch(input: string | Request, init?: RequestInit): Promise<Response>;
+}
+//# sourceMappingURL=FetchAdapter.d.ts.map

package/dist/client/FetchAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FetchAdapter.d.ts","sourceRoot":"","sources":["../../src/client/FetchAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvE"}

package/dist/client/FetchAdapter.js

@@ -0,0 +1 @@
+export {};

package/dist/client/OciRegistryClient.d.ts

@@ -0,0 +1,196 @@
+import type { Manifest, ManifestOCI, ManifestOCIDescriptor, ObsidianManifest } from "../types/ManifestTypes.js";
+import type { RegistryRepo, TagList } from "../types/RegistryTypes.js";
+import type { AuthInfo } from "../types/AuthTypes.js";
+import type { RegistryClientOptions } from "./RegistryClientOptions.js";
+export declare class OciRegistryClient {
+    readonly version = 2;
+    insecure: boolean;
+    repo: RegistryRepo;
+    acceptOCIManifests: boolean;
+    acceptManifestLists: boolean;
+    username?: string;
+    password?: string;
+    scopes: string[];
+    private _loggedIn;
+    private _loggedInScope?;
+    private _authInfo?;
+    private _headers;
+    private _url;
+    private _userAgent;
+    private readonly _adapter;
+    /**
+     * Create a new GHCR client for a particular repository.
+     *
+     * @param opts.insecure {Boolean} Optional. Default false. Set to true
+     *      to *not* fail on an invalid or this-signed server certificate.
+     * @param opts.adapter {FetchAdapter} Required. HTTP adapter for making requests.
+     * ... TODO: lots more to document
+     *
+     */
+    constructor(opts: RegistryClientOptions);
+    /**
+     * Login V2
+     *
+     * Typically one does not need to call this function directly because most
+     * methods of a `GHCRClient` will automatically login as necessary.
+     *
+     * @param opts {Object}
+     *      - opts.scope {String} Optional. A scope string passed in for
+     *        bearer/token auth. If this is just a login request where the token
+     *        won't be used, then the empty string (the default) is sufficient.
+     *        // JSSTYLED
+     *        See <https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md#requesting-a-token>
+     * @return an object with authentication info
+     */
+    performLogin(opts: {
+        scope?: string;
+    }): Promise<AuthInfo>;
+    /**
+     * Get an auth token.
+     *
+     * See: docker/docker.git:registry/token.go
+     */
+    _getToken(opts: {
+        realm: string;
+        service?: string;
+        scopes?: string[];
+    }): Promise<string>;
+    /**
+     * Get a registry session (i.e. login to the registry).
+     *
+     * Typically one does not need to call this method directly because most
+     * methods of a client will automatically login as necessary.
+     *
+     * @param opts {Object} Optional.
+     *      - opts.scope {String} Optional. Scope to use in the auth Bearer token.
+     *
+     * Side-effects:
+     * - On success, all of `this._loggedIn*`, `this._authInfo`, and
+     *   `this._headers.authorization` are set.
+     */
+    login(opts?: {
+        scope?: string;
+    }): Promise<void>;
+    listTags(props?: {
+        pageSize?: number;
+        startingAfter?: string;
+    }): Promise<TagList>;
+    listAllTags(props?: {
+        pageSize?: number;
+    }): Promise<TagList>;
+    listTagsPaginated(props?: {
+        pageSize?: number;
+    }): AsyncGenerator<TagList>;
+    getManifest(opts: {
+        ref: string;
+        acceptManifestLists?: boolean;
+        acceptOCIManifests?: boolean;
+        followRedirects?: boolean;
+    }): Promise<{
+        resp: Response;
+        manifest: Manifest;
+    }>;
+    /**
+     * Makes a http request to the given url, following any redirects, then fires
+     * the callback(err, req, responses) with the result.
+     *
+     * Note that 'responses' is an *array* of Response objects, with
+     * the last response being at the end of the array. When there is more than
+     * one response, it means a redirect has been followed.
+     */
+    _makeHttpRequest(opts: {
+        method: string;
+        path: string;
+        headers?: Record<string, string>;
+        followRedirects?: boolean;
+        maxRedirects?: number;
+    }): Promise<Response[]>;
+    _headOrGetBlob(method: "GET" | "HEAD", digest: string): Promise<Response[]>;
+    headBlob(opts: {
+        digest: string;
+    }): Promise<Response[]>;
+    /**
+     * Download a blob and return its ArrayBuffer.
+     * <https://docs.docker.com/registry/spec/api/#get-blob>
+     *
+     * @return
+     *      The `buffer` is the blob's content as an ArrayBuffer.
+     *      `ress` (plural of 'res') is an array of responses
+     *      after following redirects. The full set of responses are returned mainly because
+     *      headers on both the first, e.g. 'Docker-Content-Digest', and last,
+     *      e.g. 'Content-Length', might be interesting.
+     */
+    downloadBlob(opts: {
+        digest: string;
+    }): Promise<{
+        ress: Response[];
+        buffer: ArrayBuffer;
+    }>;
+    /**
+     * Upload a blob using POST then PUT workflow.
+     * <https://github.com/opencontainers/distribution-spec/blob/main/spec.md#post-then-put>
+     *
+     * @param opts.data The blob data as ArrayBuffer or Uint8Array
+     * @param opts.digest Optional digest. If not provided, it will be calculated.
+     * @returns Object with digest and size of the uploaded blob
+     */
+    pushBlob(opts: {
+        data: ArrayBuffer | Uint8Array;
+    }): Promise<{
+        digest: string;
+        size: number;
+    }>;
+    /**
+     * Upload an image manifest.
+     * <https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests>
+     *
+     * @param opts.ref The tag or digest to push to
+     * @param opts.manifest The manifest object to upload
+     * @param opts.mediaType Optional media type (defaults to OCI manifest type)
+     * @returns Object with digest and size of the uploaded manifest
+     */
+    pushManifest(opts: {
+        ref: string;
+        manifest: Manifest;
+        mediaType?: string;
+    }): Promise<{
+        digest: string;
+        size: number;
+    }>;
+    /**
+     * Push a plugin manifest as a config blob and create an OCI manifest.
+     * This follows the OCI spec where the Obsidian manifest is stored as the config.
+     *
+     * @param opts.ref The tag or digest to push to
+     * @param opts.pluginManifest The Obsidian plugin manifest
+     * @param opts.layers The layer descriptors (main.js, styles.css, etc.)
+     * @param opts.annotations Optional annotations for the OCI manifest
+     * @returns Object with digest, configDigest, and the created manifest
+     */
+    pushPluginManifest(opts: {
+        ref: string;
+        pluginManifest: ObsidianManifest;
+        layers: ManifestOCIDescriptor[];
+        annotations?: Record<string, string>;
+    }): Promise<{
+        digest: string;
+        configDigest: string;
+        manifest: ManifestOCI;
+    }>;
+    /**
+     * Pull a plugin manifest by extracting it from the OCI config blob.
+     * This follows the OCI spec where the Obsidian manifest is stored as the config.
+     *
+     * @param opts.ref The tag or digest to pull
+     * @returns Object with the plugin manifest, OCI manifest, and digests
+     */
+    pullPluginManifest(opts: {
+        ref: string;
+    }): Promise<{
+        pluginManifest: ObsidianManifest;
+        manifest: ManifestOCI;
+        manifestDigest: string;
+        configDigest: string;
+    }>;
+}
+//# sourceMappingURL=OciRegistryClient.d.ts.map

package/dist/client/OciRegistryClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OciRegistryClient.d.ts","sourceRoot":"","sources":["../../src/client/OciRegistryClient.ts"],"names":[],"mappings":"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"}