paperplane-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ArcOps
+
+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,51 @@
-# Temporary Holding Version
+# Paperplane Client SDK (`paperplane-sdk`)
 
-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.
+Official zero-dependency JavaScript & TypeScript client library for Paperplane passwordless OTP and messaging engine.
+
+Supports **WhatsApp**, **SMS**, and **Amazon SES Email** OTP dispatch and stateless verification with **$0.00 verification fee**.
+
+## Installation
+
+```bash
+npm install paperplane-sdk
+```
+
+## Quickstart
+
+```typescript
+import { pp } from "paperplane-sdk";
+
+// 1. Send WhatsApp OTP
+const sent = await pp.send("+918279012305");
+console.log(sent); // => { status: "queued", channel: "whatsapp", to: "+918279012305" }
+
+// 2. Verify 6-digit Code ($0.00 fee)
+const res = await pp.verify("+918279012305", "375666");
+if (res.verified) {
+  console.log("Logged in successfully!");
+}
+
+// 3. Inspect Delivery Logs
+const logs = await pp.logs();
+```
+
+## Configuration
+
+By default, Paperplane automatically reads `PAPERPLANE_API_KEY` (or `NEXT_PUBLIC_PAPERPLANE_KEY`) and `PAPERPLANE_URL` from your environment (falls back to `https://api.arcopscloud.in`).
+
+You can also pass custom keys programmatically:
+
+```typescript
+import { PaperplaneClient } from "paperplane-sdk";
+
+const client = new PaperplaneClient({
+  apiKey: "pp_live_your_key_here",
+  baseUrl: "https://api.arcopscloud.in",
+});
+
+await client.send("+918279012305");
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Paperplane — Zero-dependency client library for the Paperplane passwordless OTP engine.
+ * Supports WhatsApp, SMS, and Amazon SES Email with $0.00 verification fees.
+ */
+export type DeliveryChannel = "whatsapp" | "email" | "sms";
+export interface SendOtpOptions {
+    to: string;
+    channel?: DeliveryChannel;
+    appName?: string;
+    code?: string;
+    otp?: string;
+    tenantId?: string;
+}
+export interface SendOtpResult {
+    status: string;
+    channel: string;
+    to: string;
+    error?: string;
+    [key: string]: any;
+}
+export interface VerifyOtpOptions {
+    to: string;
+    otp: string;
+    code?: string;
+    tenantId?: string;
+}
+export interface VerifyOtpResult {
+    verified: boolean;
+    channel?: string;
+    error?: string;
+    [key: string]: any;
+}
+export interface LogFilterOptions {
+    date?: string;
+    limit?: number;
+}
+export interface DeliveryLogItem {
+    id: string;
+    to: string;
+    channel: string;
+    status: string;
+    createdAt: string;
+    [key: string]: any;
+}
+export interface LogsResponse {
+    date?: string;
+    count: number;
+    logs: DeliveryLogItem[];
+    tenant_id?: string;
+}
+export interface PaperplaneConfig {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export declare class PaperplaneClient {
+    apiKey: string;
+    baseUrl: string;
+    constructor(apiKeyOrConfig?: string | PaperplaneConfig);
+    /**
+     * 1. Send OTP via WhatsApp, Email, or SMS
+     * @param to Phone number "+918279012305" or email "user@example.com"
+     * @param channel "whatsapp" (default), "email", or "sms"
+     * @param appName Brand name shown in the copy-code template
+     */
+    send(toOrOptions: string | SendOtpOptions, channel?: DeliveryChannel, appName?: string): Promise<SendOtpResult>;
+    /**
+     * 2. Verify OTP code ($0.00 verification fee forever)
+     * @param to Recipient phone or email originally sent to
+     * @param otp 6-digit verification code entered by user
+     */
+    verify(toOrOptions: string | VerifyOtpOptions, otp?: string): Promise<VerifyOtpResult>;
+    /**
+     * 3. Fetch real-time delivery logs
+     * @param optionsOrLimit Limit number or options object { date: "YYYY-MM-DD", limit: 50 }
+     */
+    logs(optionsOrLimit?: number | LogFilterOptions): Promise<LogsResponse>;
+}
+export declare const pp: PaperplaneClient;
+export declare function createPaperplane(apiKeyOrConfig?: string | PaperplaneConfig): PaperplaneClient;
+export default pp;

package/dist/index.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Paperplane — Zero-dependency client library for the Paperplane passwordless OTP engine.
+ * Supports WhatsApp, SMS, and Amazon SES Email with $0.00 verification fees.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pp = exports.PaperplaneClient = void 0;
+exports.createPaperplane = createPaperplane;
+const DEFAULT_API_BASE = (typeof process !== "undefined" && (process.env.NEXT_PUBLIC_PAPERPLANE_URL || process.env.PAPERPLANE_URL)) ||
+    "https://api.arcopscloud.in";
+class PaperplaneClient {
+    constructor(apiKeyOrConfig) {
+        if (typeof apiKeyOrConfig === "string") {
+            this.apiKey = apiKeyOrConfig;
+            this.baseUrl = DEFAULT_API_BASE;
+        }
+        else if (apiKeyOrConfig && typeof apiKeyOrConfig === "object") {
+            this.apiKey = apiKeyOrConfig.apiKey || "";
+            this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_API_BASE;
+        }
+        else {
+            this.apiKey =
+                typeof process !== "undefined"
+                    ? process.env.NEXT_PUBLIC_PAPERPLANE_KEY ||
+                        process.env.PAPERPLANE_API_KEY ||
+                        process.env.ARCOPS_API_KEY ||
+                        ""
+                    : "";
+            this.baseUrl = DEFAULT_API_BASE;
+        }
+    }
+    /**
+     * 1. Send OTP via WhatsApp, Email, or SMS
+     * @param to Phone number "+918279012305" or email "user@example.com"
+     * @param channel "whatsapp" (default), "email", or "sms"
+     * @param appName Brand name shown in the copy-code template
+     */
+    async send(toOrOptions, channel = "whatsapp", appName = "Paperplane") {
+        let payload;
+        if (typeof toOrOptions === "string") {
+            payload = {
+                to: toOrOptions,
+                channel,
+                app_name: appName,
+            };
+        }
+        else {
+            payload = {
+                to: toOrOptions.to,
+                channel: toOrOptions.channel || "whatsapp",
+                app_name: toOrOptions.appName || "Paperplane",
+            };
+            if (toOrOptions.code)
+                payload.code = toOrOptions.code;
+            if (toOrOptions.otp)
+                payload.otp = toOrOptions.otp;
+            if (toOrOptions.tenantId)
+                payload.tenant_id = toOrOptions.tenantId;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const url = `${this.baseUrl.replace(/\/$/, "")}/send`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+        });
+        return res.json();
+    }
+    /**
+     * 2. Verify OTP code ($0.00 verification fee forever)
+     * @param to Recipient phone or email originally sent to
+     * @param otp 6-digit verification code entered by user
+     */
+    async verify(toOrOptions, otp) {
+        let payload;
+        if (typeof toOrOptions === "string") {
+            payload = {
+                to: toOrOptions,
+                otp: otp || "",
+            };
+        }
+        else {
+            payload = {
+                to: toOrOptions.to,
+                otp: toOrOptions.otp || toOrOptions.code || "",
+            };
+            if (toOrOptions.tenantId)
+                payload.tenant_id = toOrOptions.tenantId;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const url = `${this.baseUrl.replace(/\/$/, "")}/verify`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+        });
+        return res.json();
+    }
+    /**
+     * 3. Fetch real-time delivery logs
+     * @param optionsOrLimit Limit number or options object { date: "YYYY-MM-DD", limit: 50 }
+     */
+    async logs(optionsOrLimit) {
+        let date = "";
+        let limit = 50;
+        if (typeof optionsOrLimit === "number") {
+            limit = optionsOrLimit;
+        }
+        else if (optionsOrLimit && typeof optionsOrLimit === "object") {
+            if (optionsOrLimit.date)
+                date = optionsOrLimit.date;
+            if (optionsOrLimit.limit)
+                limit = optionsOrLimit.limit;
+        }
+        const params = new URLSearchParams();
+        if (date)
+            params.set("date", date);
+        if (limit)
+            params.set("limit", limit.toString());
+        const headers = {};
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        const url = `${this.baseUrl.replace(/\/$/, "")}/logs${qs}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        return res.json();
+    }
+}
+exports.PaperplaneClient = PaperplaneClient;
+// Default export: pre-configured singleton instance
+exports.pp = new PaperplaneClient();
+// Helper factory
+function createPaperplane(apiKeyOrConfig) {
+    return new PaperplaneClient(apiKeyOrConfig);
+}
+exports.default = exports.pp;

package/dist/index.mjs

@@ -0,0 +1,145 @@
+/**
+ * Paperplane — Zero-dependency client library for the Paperplane passwordless OTP engine.
+ * Supports WhatsApp, SMS, and Amazon SES Email with $0.00 verification fees.
+ */
+const DEFAULT_API_BASE = (typeof process !== "undefined" && (process.env.NEXT_PUBLIC_PAPERPLANE_URL || process.env.PAPERPLANE_URL)) ||
+    "https://api.arcopscloud.in";
+export class PaperplaneClient {
+    constructor(apiKeyOrConfig) {
+        if (typeof apiKeyOrConfig === "string") {
+            this.apiKey = apiKeyOrConfig;
+            this.baseUrl = DEFAULT_API_BASE;
+        }
+        else if (apiKeyOrConfig && typeof apiKeyOrConfig === "object") {
+            this.apiKey = apiKeyOrConfig.apiKey || "";
+            this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_API_BASE;
+        }
+        else {
+            this.apiKey =
+                typeof process !== "undefined"
+                    ? process.env.NEXT_PUBLIC_PAPERPLANE_KEY ||
+                        process.env.PAPERPLANE_API_KEY ||
+                        process.env.ARCOPS_API_KEY ||
+                        ""
+                    : "";
+            this.baseUrl = DEFAULT_API_BASE;
+        }
+    }
+    /**
+     * 1. Send OTP via WhatsApp, Email, or SMS
+     * @param to Phone number "+918279012305" or email "user@example.com"
+     * @param channel "whatsapp" (default), "email", or "sms"
+     * @param appName Brand name shown in the copy-code template
+     */
+    async send(toOrOptions, channel = "whatsapp", appName = "Paperplane") {
+        let payload;
+        if (typeof toOrOptions === "string") {
+            payload = {
+                to: toOrOptions,
+                channel,
+                app_name: appName,
+            };
+        }
+        else {
+            payload = {
+                to: toOrOptions.to,
+                channel: toOrOptions.channel || "whatsapp",
+                app_name: toOrOptions.appName || "Paperplane",
+            };
+            if (toOrOptions.code)
+                payload.code = toOrOptions.code;
+            if (toOrOptions.otp)
+                payload.otp = toOrOptions.otp;
+            if (toOrOptions.tenantId)
+                payload.tenant_id = toOrOptions.tenantId;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const url = `${this.baseUrl.replace(/\/$/, "")}/send`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+        });
+        return res.json();
+    }
+    /**
+     * 2. Verify OTP code ($0.00 verification fee forever)
+     * @param to Recipient phone or email originally sent to
+     * @param otp 6-digit verification code entered by user
+     */
+    async verify(toOrOptions, otp) {
+        let payload;
+        if (typeof toOrOptions === "string") {
+            payload = {
+                to: toOrOptions,
+                otp: otp || "",
+            };
+        }
+        else {
+            payload = {
+                to: toOrOptions.to,
+                otp: toOrOptions.otp || toOrOptions.code || "",
+            };
+            if (toOrOptions.tenantId)
+                payload.tenant_id = toOrOptions.tenantId;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const url = `${this.baseUrl.replace(/\/$/, "")}/verify`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+        });
+        return res.json();
+    }
+    /**
+     * 3. Fetch real-time delivery logs
+     * @param optionsOrLimit Limit number or options object { date: "YYYY-MM-DD", limit: 50 }
+     */
+    async logs(optionsOrLimit) {
+        let date = "";
+        let limit = 50;
+        if (typeof optionsOrLimit === "number") {
+            limit = optionsOrLimit;
+        }
+        else if (optionsOrLimit && typeof optionsOrLimit === "object") {
+            if (optionsOrLimit.date)
+                date = optionsOrLimit.date;
+            if (optionsOrLimit.limit)
+                limit = optionsOrLimit.limit;
+        }
+        const params = new URLSearchParams();
+        if (date)
+            params.set("date", date);
+        if (limit)
+            params.set("limit", limit.toString());
+        const headers = {};
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        const url = `${this.baseUrl.replace(/\/$/, "")}/logs${qs}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        return res.json();
+    }
+}
+// Default export: pre-configured singleton instance
+export const pp = new PaperplaneClient();
+// Helper factory
+export function createPaperplane(apiKeyOrConfig) {
+    return new PaperplaneClient(apiKeyOrConfig);
+}
+export default pp;

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "paperplane-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Zero-dependency client SDK for Paperplane passwordless OTP and messaging engine",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "paperplane",
+    "otp",
+    "whatsapp",
+    "sms",
+    "email",
+    "passwordless",
+    "auth",
+    "arcops",
+    "sdk"
+  ],
+  "author": "ArcOps",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}