sbcwallet 0.0.1

package/README.md

@@ -0,0 +1,187 @@
+# 🎟️ sbcwallet
+
+Unified Wallet-Pass SDK for Real-World Credentials
+
+sbcwallet is a TypeScript SDK for generating, signing, and managing verifiable passes on Apple Wallet and Google Wallet.
+Built on @sbcwallet, it bridges cryptographic truth and real-world credentials — enabling secure, interoperable workflows for logistics, healthcare, and beyond.
+
+⸻
+
+## ✨ Overview
+
+sbcwallet provides a unified abstraction layer for issuing and updating wallet passes across multiple ecosystems.
+It standardizes claim flows (like PES → TO) and status pipelines (ISSUED → PRESENCE → OPS → EXITED) while maintaining verifiable hashes, signatures, and anchor integrity via sbcwallet Core.
+
+⸻
+
+## 🚀 Quickstart
+
+```jsnpm install sbcwallet
+
+import { createParentSchedule, createChildTicket, getPkpassBuffer } from 'sbcwallet'
+
+// 1️⃣ Create a parent PES schedule
+const pes = await createParentSchedule({
+  profile: 'logistics',
+  programName: 'Morning Yard Veracruz',
+  site: 'Patio Gate 3'
+})
+
+// 2️⃣ Claim a child Transport Order
+const to = await createChildTicket({
+  parentId: pes.id,
+  plate: 'ABC123A',
+  carrier: 'Transportes Golfo'
+})
+
+// 3️⃣ Generate Apple Wallet pass
+const buf = await getPkpassBuffer('child', to)
+await fs.promises.writeFile('ticket.pkpass', buf)
+```
+
+## 🎁 Loyalty Cards (Multi-tenant)
+
+Each business defines its own loyalty program, customers create accounts, and each customer gets a loyalty card that shows:
+- A QR/barcode identifier (`memberId`)
+- Current points (`points`) which can be updated
+
+```ts
+import {
+	createBusiness,
+	createCustomerAccount,
+	createLoyaltyProgram,
+	issueLoyaltyCard,
+	updateLoyaltyPoints,
+	getGoogleObject
+} from 'sbcwallet'
+
+const biz = createBusiness({ name: 'SBC Coffee', pointsLabel: 'Beans' })
+await createLoyaltyProgram({ businessId: biz.id })
+
+const customer = createCustomerAccount({ businessId: biz.id, fullName: 'Alice' })
+const card = await issueLoyaltyCard({ businessId: biz.id, customerId: customer.id, initialPoints: 10 })
+await updateLoyaltyPoints({ cardId: card.id, delta: 5 })
+
+const { saveUrl } = await getGoogleObject('child', card)
+console.log(saveUrl)
+```
+
+⸻
+
+## 🧠 Architecture
+```bash
+sbcwallet
+├── adapters/      # Apple + Google Wallet adapters
+├── api/           # Unified issuance/update API
+├── profiles/      # Domain-specific field maps
+├── templates/     # JSON templates for passes
+└── types.ts       # Shared types and validation
+```
+### Key Components
+```bash
+Module	Description
+adapters/apple.ts	Builds and signs .pkpass files using passkit-generator.
+adapters/google.ts	Creates Google Wallet class/object JSON payloads.
+api/unified.ts	Unified functions: createParentSchedule, createChildTicket, updatePassStatus.
+profiles/	Domain-specific mappings (logistics, healthcare, etc.).
+templates/	JSON templates for field mapping and layout.
+```
+
+⸻
+
+## 🧩 Profiles
+
+### Logistics (default)
+
+Entity	Description	Example
+Parent (PES)	Program Entry Schedule	Gate window, site, available slots
+Child (TO)	Transport Order	Plate, carrier, client, status
+Statuses	ISSUED → PRESENCE → SCALE → OPS → EXITED	
+
+### Healthcare (reference)
+
+Entity	Description	Example
+Parent	Appointment Batch	Doctor, location, date
+Child	Patient Visit Ticket	Patient, procedure, status
+Statuses	SCHEDULED → CHECKIN → PROCEDURE → DISCHARGED	
+
+Switch profiles dynamically:
+```js
+await createChildTicket({ profile: 'healthcare', ... })
+```
+
+⸻
+
+## 🔐 Integration with sbcwallet Core
+
+sbcwallet Pass automatically uses:
+	•	hashEvent() for deterministic hashes
+	•	signCredential() for ECDSA signatures
+	•	dailyMerkle() for anchoring batches
+
+This ensures every pass is cryptographically verifiable and compatible with sbcwallet’s event audit trail.
+
+⸻
+
+## 🧪 Testing
+
+`npm run test`
+
+Tests include:
+	•	Apple .pkpass field mapping
+	•	Google Wallet JSON validity
+	•	Cross-profile field validation
+	•	Core integration (hash + sign + verify)
+
+⸻
+
+## ⚙️ Environment Variables (Apple Wallet)
+
+```sh
+APPLE_TEAM_ID=ABCD1234
+APPLE_PASS_TYPE_ID=pass.com.sbcwallet.logistics
+APPLE_CERT_PATH=./certs/pass.p12
+APPLE_CERT_PASSWORD=yourpassword
+APPLE_WWDR_PATH=./certs/wwdr.pem
+```
+
+For Google Wallet, include:
+```sh
+GOOGLE_ISSUER_ID=issuer-id
+GOOGLE_SA_JSON=./google/credentials.json
+```
+
+⸻
+
+## 🧾 License
+
+Apache License 2.0
+© 2025 sbcwallet — open and extensible.
+
+⸻
+
+## 🤝 Contributing
+	1.	Fork the repo
+	2.	Run npm install
+	3.	Add or improve a profile under src/profiles/
+	4.	Write tests in tests/
+	5.	Submit a PR using conventional commits
+
+⸻
+
+## 🧭 Part of the sbcwallet Ecosystem
+
+Repo	Purpose
+```sh
+sbcwallet/core	Verifiable event SDK — hashing, signing, Merkle trees
+sbcwallet/pass	Wallet-pass abstraction over Core (this repo)
+sbcwallet/wallet	Reference logistics PWA & API
+sbcwallet/id	Hosted identity & orchestration layer (SaaS)
+```
+
+⸻
+
+“sbcwallet Pass connects cryptographic truth with human experience —
+turning every credential into a verifiable story.”
+
+Reflection: evidence ✓ logic consistent brevity optimized

package/dist/adapters/apple.d.ts

@@ -0,0 +1,10 @@
+import type { PassData, ApplePassConfig, ProfileConfig } from '../types.js';
+export declare class AppleWalletAdapter {
+    private config;
+    constructor(config?: Partial<ApplePassConfig>);
+    generatePkpass(passData: PassData, profile: ProfileConfig, passType: 'parent' | 'child'): Promise<Buffer>;
+    private mergeTemplates;
+    private populateTemplate;
+    private getFieldValue;
+}
+export default AppleWalletAdapter;

package/dist/adapters/apple.js

@@ -0,0 +1,153 @@
+import { PKPass } from 'passkit-generator';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export class AppleWalletAdapter {
+    config;
+    constructor(config) {
+        this.config = {
+            teamId: config?.teamId || process.env.APPLE_TEAM_ID || '',
+            passTypeId: config?.passTypeId || process.env.APPLE_PASS_TYPE_ID || '',
+            certPath: config?.certPath || process.env.APPLE_CERT_PATH || '',
+            certPassword: config?.certPassword || process.env.APPLE_CERT_PASSWORD || '',
+            wwdrPath: config?.wwdrPath || process.env.APPLE_WWDR_PATH || ''
+        };
+    }
+    async generatePkpass(passData, profile, passType) {
+        try {
+            // Load template
+            const templatePath = join(__dirname, '..', 'templates', 'apple', `${passType}.json`);
+            const templateContent = await readFile(templatePath, 'utf-8');
+            const baseTemplate = JSON.parse(templateContent);
+            // Get profile-specific template
+            const profileTemplate = profile.defaultTemplates.apple[passType];
+            // Merge templates
+            const template = this.mergeTemplates(baseTemplate, profileTemplate);
+            // Apply pass data to template
+            const populatedTemplate = this.populateTemplate(template, passData, profile, passType);
+            // Build pass props from populated template
+            const passProps = {
+                serialNumber: passData.id,
+                description: populatedTemplate.description || 'sbcwallet Pass',
+                organizationName: populatedTemplate.organizationName || 'sbcwallet',
+                passTypeIdentifier: this.config.passTypeId,
+                teamIdentifier: this.config.teamId
+            };
+            // Add colors
+            if (populatedTemplate.backgroundColor) {
+                passProps.backgroundColor = populatedTemplate.backgroundColor;
+            }
+            if (populatedTemplate.foregroundColor) {
+                passProps.foregroundColor = populatedTemplate.foregroundColor;
+            }
+            if (populatedTemplate.labelColor) {
+                passProps.labelColor = populatedTemplate.labelColor;
+            }
+            if (populatedTemplate.logoText) {
+                passProps.logoText = populatedTemplate.logoText;
+            }
+            // Add barcodes
+            if (populatedTemplate.barcodes && populatedTemplate.barcodes.length > 0) {
+                passProps.barcodes = populatedTemplate.barcodes;
+            }
+            // Add generic fields
+            if (populatedTemplate.generic) {
+                passProps.generic = populatedTemplate.generic;
+            }
+            // Create pass
+            const pass = new PKPass({}, {
+                wwdr: this.config.wwdrPath,
+                signerCert: this.config.certPath,
+                signerKey: this.config.certPath,
+                signerKeyPassphrase: this.config.certPassword
+            }, passProps);
+            // Generate buffer
+            const buffer = await pass.getAsBuffer();
+            return buffer;
+        }
+        catch (error) {
+            throw new Error(`Failed to generate Apple Wallet pass: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    mergeTemplates(base, profile) {
+        return {
+            ...base,
+            ...profile,
+            generic: {
+                ...base.generic,
+                ...profile.generic,
+                primaryFields: profile.generic?.primaryFields || base.generic?.primaryFields,
+                secondaryFields: profile.generic?.secondaryFields || base.generic?.secondaryFields,
+                auxiliaryFields: profile.generic?.auxiliaryFields || base.generic?.auxiliaryFields,
+                backFields: profile.generic?.backFields || base.generic?.backFields,
+                headerFields: profile.generic?.headerFields || base.generic?.headerFields
+            }
+        };
+    }
+    populateTemplate(template, passData, profile, passType) {
+        const populated = { ...template };
+        if (populated.generic) {
+            // Populate primary fields
+            if (populated.generic.primaryFields) {
+                populated.generic.primaryFields = populated.generic.primaryFields.map(field => {
+                    const value = this.getFieldValue(field.key, passData);
+                    return { ...field, value: value || field.value };
+                });
+            }
+            // Populate secondary fields
+            if (populated.generic.secondaryFields) {
+                populated.generic.secondaryFields = populated.generic.secondaryFields.map(field => {
+                    const value = this.getFieldValue(field.key, passData);
+                    return { ...field, value: value || field.value };
+                });
+            }
+            // Populate auxiliary fields
+            if (populated.generic.auxiliaryFields) {
+                populated.generic.auxiliaryFields = populated.generic.auxiliaryFields.map(field => {
+                    const value = this.getFieldValue(field.key, passData);
+                    return { ...field, value: value || field.value };
+                });
+            }
+            // Populate back fields
+            if (populated.generic.backFields) {
+                populated.generic.backFields = populated.generic.backFields.map(field => {
+                    const value = this.getFieldValue(field.key, passData);
+                    return { ...field, value: value || field.value };
+                });
+            }
+        }
+        // Set barcode message
+        if (populated.barcodes && populated.barcodes.length > 0) {
+            const barcodeValue = passData.memberId || passData.id;
+            populated.barcodes[0].message = barcodeValue;
+        }
+        return populated;
+    }
+    getFieldValue(key, passData) {
+        // Handle nested keys like 'window.from'
+        const keys = key.split('.');
+        let value = passData;
+        for (const k of keys) {
+            if (value && typeof value === 'object' && k in value) {
+                value = value[k];
+            }
+            else {
+                return '';
+            }
+        }
+        // Map field names for common fields
+        if (key === 'scheduleId' || key === 'orderId' || key === 'batchId' || key === 'visitId') {
+            return passData.id;
+        }
+        if (key === 'windowFrom' && passData.type === 'parent' && passData.window) {
+            return new Date(passData.window.from).toLocaleString();
+        }
+        if (key === 'windowTo' && passData.type === 'parent' && passData.window) {
+            return new Date(passData.window.to).toLocaleString();
+        }
+        return value !== undefined && value !== null ? String(value) : '';
+    }
+}
+export default AppleWalletAdapter;

package/dist/adapters/google.d.ts

@@ -0,0 +1,26 @@
+import type { PassData, GooglePassConfig, GooglePassObject, ProfileConfig } from '../types.js';
+export declare class GoogleWalletAdapter {
+    private config;
+    private auth;
+    constructor(config?: Partial<GooglePassConfig>);
+    generatePassObject(passData: PassData, profile: ProfileConfig, passType: 'parent' | 'child'): Promise<{
+        object: GooglePassObject;
+        saveUrl: string;
+    }>;
+    private generateLoyaltyClass;
+    private populateObject;
+    private applyLoyaltyExtras;
+    private getFieldValue;
+    private generateSaveUrl;
+    private upsertInAPI;
+    /**
+     * Generate and add hero image with progress bar to the pass object
+     *
+     * Note: Google Wallet API requires publicly accessible URLs for images.
+     * This method generates the hero image and saves it locally.
+     * For production, upload images to a CDN/cloud storage and use those URLs.
+     */
+    private addHeroImage;
+    createClass(profile: ProfileConfig, passType: 'parent' | 'child'): Promise<void>;
+}
+export default GoogleWalletAdapter;