@zapwebp/sdk 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eldrex Delos Reyes Bula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="../../public/assets/packages-readme-icons/zapwebp-sdk.svg" width="120" height="120" alt="@zapwebp/sdk logo" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @zapwebp/sdk
+
+Official JavaScript and TypeScript SDK for the Zap image conversion and asset optimization platform. Works offline in-memory by default, or connects to the remote hosted Zap edge service.
+
+Documentation: [https://zapwebp.vercel.app/docs](https://zapwebp.vercel.app/docs)
+
+---
+
+## Features
+
+- **Zero-Config In-Memory Execution:** Runs completely offline by default using the `@zapwebp/core` engine. No API keys, no network requests, and zero latency in local development and CI pipelines.
+- **Remote Edge API Support:** Configure `baseUrl: 'https://zapwebp.vercel.app'` to delegate large batch workloads to the hosted serverless API.
+- **Multi-Target Bundling:** Convert an image to multiple formats simultaneously (`to: ['webp', 'avif', 'png']`) in a single call.
+- **Project Asset Optimization:** Automated directory scanning and modern format generation with byte-savings reporting.
+- **Webhook Security:** Built-in cryptographic verification for webhook payloads via HMAC SHA-256.
+
+---
+
+## Installation
+
+```bash
+pnpm add @zapwebp/sdk
+# or
+npm install @zapwebp/sdk
+```
+
+---
+
+## Quick Starts
+
+### 1. Offline Mode (Default)
+
+```typescript
+import { Zap } from '@zapwebp/sdk';
+
+// Initializes in offline mode (runs via @zapwebp/core in memory)
+const zap = new Zap();
+
+// Convert a single image
+const webp = await zap.convert('public/logo.svg', {
+  to: 'webp',
+  width: 512,
+  quality: 85,
+});
+
+console.log(`Converted bytes: ${webp.length}, Alpha preserved: ${webp.alphaPreserved}`);
+```
+
+### 2. Multi-Target Output
+
+```typescript
+// Generates WebP, AVIF, and fallback PNG variants in one pass
+const variants = await zap.convert('assets/banner.png', {
+  to: ['webp', 'avif', 'png'],
+  width: 1200,
+  quality: 80,
+});
+
+for (const variant of variants) {
+  console.log(`${variant.format}: ${variant.data.length} bytes`);
+}
+```
+
+### 3. Inspect Image Properties
+
+```typescript
+const info = await zap.inspect('assets/hero.png');
+console.log({
+  format: info.format,
+  dimensions: `${info.width}x${info.height}`,
+  hasAlpha: info.hasAlpha,
+  recommendedTargets: info.recommendedTargets,
+});
+```
+
+### 4. Optimize Directory Assets
+
+```typescript
+const report = await zap.optimize({
+  files: ['public/logo.svg', 'public/banner.png'],
+  targets: [
+    { to: 'webp', quality: 85 },
+    { to: 'avif', quality: 60 },
+  ],
+});
+
+console.log(`Saved ${report.savedPercent}% of total bytes across ${report.totalFiles} files`);
+```
+
+### 5. Remote API Mode
+
+```typescript
+// Connects to hosted Zap Edge API
+const remoteZap = new Zap({
+  baseUrl: 'https://zapwebp.vercel.app',
+  apiKey: process.env.ZAP_API_KEY,
+});
+
+const remoteResult = await remoteZap.convert('photo.jpg', { to: 'webp' });
+```
+
+### 6. Webhook Signature Verification
+
+```typescript
+import { Zap } from '@zapwebp/sdk';
+
+const isValid = Zap.verifyWebhookSignature(
+  rawBodyBuffer,
+  req.headers['x-zap-signature'],
+  process.env.ZAP_WEBHOOK_SECRET
+);
+
+if (!isValid) {
+  return res.status(401).send('Invalid webhook signature');
+}
+```
+
+---
+
+## TypeScript Types Reference
+
+```typescript
+export interface ZapOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  timeoutMs?: number;
+}
+
+export interface ConvertOptions {
+  to?: 'webp' | 'png' | 'jpeg' | 'avif' | Array<'webp' | 'png' | 'jpeg' | 'avif'>;
+  width?: number;
+  height?: number;
+  quality?: number;
+  lossless?: boolean;
+  background?: string;
+  clean?: boolean;
+  scales?: number[];
+}
+
+export interface ConvertResult {
+  format: string;
+  width: number;
+  height: number;
+  data: Buffer;
+  length: number;
+  alphaPreserved: boolean;
+  cleanCertificate?: CleanCertificate;
+}
+```
+
+---
+
+## License
+
+MIT © [Zapwebp](https://zapwebp.vercel.app/)

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@zapwebp/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Official TypeScript and JavaScript SDK for Zap / Zapwebp.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@zapwebp/core": "1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://zapwebp.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zapwebp/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Zapwebp/sdk/issues"
+  },
+  "author": "Eldrex Delos Reyes Bula <eldrexdelosreyesbula@gmail.com>",
+  "scripts": {
+    "test": "node --test"
+  }
 }

package/src/index.d.ts

@@ -0,0 +1,83 @@
+export type InputFormat = 'svg' | 'png' | 'jpeg' | 'webp' | 'avif' | 'gif' | 'tiff';
+export type OutputFormat = 'webp' | 'png' | 'jpeg' | 'avif';
+export type FitMode = 'contain' | 'cover' | 'fill' | 'inside' | 'outside';
+
+export interface ConvertOptions {
+  to?: OutputFormat | OutputFormat[];
+  width?: number;
+  height?: number;
+  fit?: FitMode;
+  quality?: number;
+  lossless?: boolean;
+  effort?: number;
+  background?: string;
+  stripMetadata?: boolean;
+}
+
+export interface ConvertResult {
+  data: Buffer;
+  format: OutputFormat;
+  width: number;
+  height: number;
+  size: number;
+  alphaPreserved: boolean;
+}
+
+export interface ImageInspection {
+  format: InputFormat;
+  width?: number;
+  height?: number;
+  hasAlpha: boolean;
+  bytes: number;
+  recommendedTargets: Array<{ to: OutputFormat; reason: string }>;
+}
+
+export interface OptimizeTarget {
+  to: OutputFormat;
+  quality?: number;
+  width?: number;
+}
+
+export interface OptimizeResult {
+  totalBytesBefore: number;
+  totalBytesAfter: number;
+  savedPercent: number;
+  files: Array<{
+    input: string;
+    inputBytes: number;
+    outputs: Array<{
+      format: OutputFormat;
+      bytes: number;
+      width: number;
+      height: number;
+      alphaPreserved: boolean;
+    }>;
+    savedPercent: number;
+  }>;
+}
+
+export interface ZapClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+export class Zap {
+  constructor(options?: ZapClientOptions);
+  apiKey: string | null;
+  baseUrl: string | null;
+  isOffline: boolean;
+
+  convert(input: Buffer | Uint8Array | string, options?: ConvertOptions & { to?: OutputFormat }): Promise<Buffer & ConvertResult>;
+  convert(input: Buffer | Uint8Array | string, options: ConvertOptions & { to: OutputFormat[] }): Promise<ConvertResult[]>;
+  inspect(input: Buffer | Uint8Array | string): Promise<ImageInspection>;
+  batch(inputs: Array<Buffer | Uint8Array | string>, options?: ConvertOptions): Promise<Array<Buffer & ConvertResult>>;
+  optimize(options: { files?: Array<string | Buffer>; targets?: OptimizeTarget[] }): Promise<OptimizeResult>;
+
+  static verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+}
+
+export function createZapClient(options?: ZapClientOptions): Zap;
+
+export const INPUT_FORMATS: readonly InputFormat[];
+export const OUTPUT_FORMATS: readonly OutputFormat[];
+

package/src/index.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const core = require('@zapwebp/core');
+
+const { convertImage, convert, inspectImage, detectFormat, outputName, INPUT_FORMATS, OUTPUT_FORMATS } = core;
+
+/**
+ * Normalizes input into a Buffer.
+ * @param {Buffer|Uint8Array|string} input - File path, URL, or raw bytes
+ * @returns {Promise<{ buffer: Buffer, filename: string }>}
+ */
+async function resolveInput(input) {
+  if (Buffer.isBuffer(input)) {
+    return { buffer: input, filename: 'input.bin' };
+  }
+  if (input instanceof Uint8Array) {
+    return { buffer: Buffer.from(input.buffer, input.byteOffset, input.byteLength), filename: 'input.bin' };
+  }
+  if (typeof input === 'string') {
+    if (/^https?:\/\//i.test(input)) {
+      const res = await fetch(input);
+      if (!res.ok) throw new Error(`Failed to fetch image from URL: ${input} (${res.status} ${res.statusText})`);
+      const arrayBuf = await res.arrayBuffer();
+      const urlPath = new URL(input).pathname;
+      return { buffer: Buffer.from(arrayBuf), filename: path.basename(urlPath) || 'image.bin' };
+    }
+    const resolved = path.resolve(input);
+    const data = await fs.readFile(resolved);
+    return { buffer: data, filename: path.basename(resolved) };
+  }
+  throw new Error('Input must be a file path string, URL, Buffer, or Uint8Array.');
+}
+
+class Zap {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.apiKey] - Optional API key (defaults to process.env.ZAP_API_KEY)
+   * @param {string} [options.baseUrl] - Optional API endpoint (enables remote HTTP execution)
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.ZAP_API_KEY || null;
+    this.baseUrl = options.baseUrl ? options.baseUrl.replace(/\/$/, '') : null;
+    this.isOffline = !this.baseUrl && !this.apiKey;
+  }
+
+  /**
+   * Converts an image to one or multiple target formats.
+   * @param {Buffer|Uint8Array|string} input
+   * @param {object} [options]
+   * @returns {Promise<Buffer|Array<{ format: string, data: Buffer, width: number, height: number, size: number, alphaPreserved: boolean }>>}
+   */
+  async convert(input, options = {}) {
+    const { buffer } = await resolveInput(input);
+    const targets = Array.isArray(options.to) ? options.to : null;
+
+    if (targets && targets.length > 0) {
+      const results = await Promise.all(
+        targets.map((to) => convertImage(buffer, { ...options, to }))
+      );
+      return results.map((r) => ({
+        format: r.format,
+        data: r.data,
+        width: r.width,
+        height: r.height,
+        size: r.size,
+        alphaPreserved: r.alphaPreserved,
+      }));
+    }
+
+    if (this.isOffline) {
+      return convert(buffer, options);
+    }
+
+    // Remote API mode
+    const formData = new FormData();
+    formData.append('svg', new Blob([buffer]), 'input.bin');
+    if (options.to) formData.append('to', options.to);
+    if (options.width) formData.append('width', String(options.width));
+    if (options.height) formData.append('height', String(options.height));
+    if (options.quality) formData.append('quality', String(options.quality));
+    if (options.lossless !== undefined) formData.append('lossless', String(options.lossless));
+    if (options.background) formData.append('background', options.background);
+    if (options.fit) formData.append('fit', options.fit);
+
+    const headers = {};
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+
+    const res = await fetch(`${this.baseUrl}/api/v1/convert`, {
+      method: 'POST',
+      body: formData,
+      headers,
+    });
+
+    if (!res.ok) {
+      const errorJson = await res.json().catch(() => ({}));
+      throw new Error(errorJson.error || `Zap API error: ${res.status} ${res.statusText}`);
+    }
+
+    const outBuf = Buffer.from(await res.arrayBuffer());
+    outBuf.format = options.to || 'webp';
+    outBuf.width = Number(res.headers.get('x-zapwebp-width')) || 0;
+    outBuf.height = Number(res.headers.get('x-zapwebp-height')) || 0;
+    outBuf.alphaPreserved = res.headers.get('x-zapwebp-alpha-preserved') === 'true';
+    outBuf.size = outBuf.length;
+    outBuf.data = outBuf;
+    return outBuf;
+  }
+
+  /**
+   * Inspects image properties, dimensions, transparency, and returns target suggestions.
+   * @param {Buffer|Uint8Array|string} input
+   * @returns {Promise<{ format: string, width?: number, height?: number, hasAlpha: boolean, bytes: number, recommendedTargets: Array<{ to: string, reason: string }> }>}
+   */
+  async inspect(input) {
+    const { buffer } = await resolveInput(input);
+    const details = await inspectImage(buffer);
+    const recommendedTargets = details.hasAlpha
+      ? [
+          { to: 'webp', reason: 'preserves transparency with compact output' },
+          { to: 'png', reason: 'lossless transparency fallback' },
+          { to: 'avif', reason: 'modern compact format with alpha support' },
+        ]
+      : [
+          { to: 'avif', reason: 'compact photographic output' },
+          { to: 'webp', reason: 'broad modern web support' },
+          { to: 'jpeg', reason: 'widely compatible photographic output' },
+        ];
+    return {
+      ...details,
+      recommendedTargets,
+    };
+  }
+
+  /**
+   * Converts a collection of images concurrently.
+   * @param {Array<Buffer|Uint8Array|string>} inputs
+   * @param {object} [options]
+   * @returns {Promise<Array<any>>}
+   */
+  async batch(inputs, options = {}) {
+    if (!Array.isArray(inputs)) throw new Error('inputs must be an array.');
+    return Promise.all(inputs.map((item) => this.convert(item, options)));
+  }
+
+  /**
+   * Project-level asset optimization tool.
+   * @param {object} options
+   * @param {Array<string|Buffer>} [options.files]
+   * @param {Array<{ to: string, quality?: number, width?: number }>} [options.targets]
+   * @returns {Promise<{ totalBytesBefore: number, totalBytesAfter: number, savedPercent: number, files: Array<any> }>}
+   */
+  async optimize(options = {}) {
+    const files = options.files || [];
+    const targets = options.targets || [{ to: 'webp', quality: 85 }, { to: 'avif', quality: 55 }];
+    let totalBytesBefore = 0;
+    let totalBytesAfter = 0;
+    const fileReports = [];
+
+    for (const file of files) {
+      const { buffer, filename } = await resolveInput(file);
+      totalBytesBefore += buffer.length;
+      const outputs = [];
+      let fileOutputBytes = 0;
+
+      for (const target of targets) {
+        const converted = await convertImage(buffer, target);
+        fileOutputBytes += converted.size;
+        outputs.push({
+          format: converted.format,
+          bytes: converted.size,
+          width: converted.width,
+          height: converted.height,
+          alphaPreserved: converted.alphaPreserved,
+        });
+      }
+
+      totalBytesAfter += fileOutputBytes;
+      const saved = buffer.length ? Number(((buffer.length - fileOutputBytes) / buffer.length * 100).toFixed(1)) : 0;
+      fileReports.push({
+        input: filename,
+        inputBytes: buffer.length,
+        outputs,
+        savedPercent: saved,
+      });
+    }
+
+    const savedPercent = totalBytesBefore
+      ? Number(((totalBytesBefore - totalBytesAfter) / totalBytesBefore * 100).toFixed(1))
+      : 0;
+
+    return {
+      totalBytesBefore,
+      totalBytesAfter,
+      savedPercent,
+      files: fileReports,
+    };
+  }
+
+  /**
+   * Verifies an incoming webhook HMAC-SHA256 signature.
+   * @param {string|Buffer} payload - Raw request body
+   * @param {string} signature - Header signature (e.g., "sha256=...")
+   * @param {string} secret - Webhook secret key
+   * @returns {boolean}
+   */
+  static verifyWebhookSignature(payload, signature, secret) {
+    if (!payload || !signature || !secret) return false;
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(typeof payload === 'string' ? payload : Buffer.from(payload))
+      .digest('hex');
+    const provided = signature.replace(/^sha256=/i, '').trim();
+    if (expected.length !== provided.length) return false;
+    return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(provided, 'hex'));
+  }
+}
+
+function createZapClient(options) {
+  return new Zap(options);
+}
+
+module.exports = {
+  Zap,
+  createZapClient,
+  INPUT_FORMATS,
+  OUTPUT_FORMATS,
+};
+