sbcwallet 0.0.1 → 0.0.3

package/README.md

@@ -1,187 +1,148 @@
-# 🎟️ sbcwallet
+# sbcwallet
 
-Unified Wallet-Pass SDK for Real-World Credentials
+Unified wallet-pass SDK for Apple Wallet (.pkpass) and Google Wallet.
 
-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.
+## Install
 
-⸻
-
-## ✨ 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.
-
-⸻
+```sh
+npm install sbcwallet
+```
 
-## 🚀 Quickstart
+## Quickstart (Loyalty)
 
-```jsnpm install sbcwallet
+Multi-tenant loyalty is designed for a real-world setup:
+- Each business (tenant) defines its own card design (logo, colors, issuer name).
+- Users add a card using their own `memberId`.
+- Points can be updated for an existing issued card.
 
-import { createParentSchedule, createChildTicket, getPkpassBuffer } from 'sbcwallet'
+### Define a business (per-tenant theme) and create its program
 
-// 1️⃣ Create a parent PES schedule
-const pes = await createParentSchedule({
-  profile: 'logistics',
-  programName: 'Morning Yard Veracruz',
-  site: 'Patio Gate 3'
+```ts
+import { createBusiness, createLoyaltyProgram } from 'sbcwallet'
+
+const biz = createBusiness({
+	name: 'X Cafe',
+	programName: 'Spirit Rewards',
+	pointsLabel: 'Points',
+	wallet: {
+		googleWallet: {
+			issuerName: 'X Cafe',
+			backgroundColor: '#111827',
+			logoUrl: 'https://example.com/logo.png',
+
+			// Advanced passthrough: merged into the Google loyaltyClass payload
+			classOverrides: {
+				reviewStatus: 'UNDER_REVIEW'
+			}
+		},
+		appleWallet: {
+			organizationName: 'X Cafe',
+			logoText: 'X',
+			backgroundColor: 'rgb(17, 24, 39)',
+
+			// Advanced passthrough: merged into the Apple pass.json payload
+			passOverrides: {
+				userInfo: { tenant: 'spirit-hub' }
+			}
+		}
+	}
 })
 
-// 2️⃣ Claim a child Transport Order
-const to = await createChildTicket({
-  parentId: pes.id,
-  plate: 'ABC123A',
-  carrier: 'Transportes Golfo'
+await createLoyaltyProgram({
+	businessId: biz.id,
+	locations: [
+		{ latitude: 35.6892, longitude: 51.389 },
+		{ latitude: 35.7, longitude: 51.4 }
+	],
+	// Apple Wallet: shown when the pass becomes relevant (e.g., near a location)
+	relevantText: 'Welcome back — show this card at checkout',
+	countryCode: 'OM',
+	homepageUrl: 'https://example.com'
 })
-
-// 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
+### Issue a card and generate a Save URL
 
 ```ts
 import {
-	createBusiness,
 	createCustomerAccount,
-	createLoyaltyProgram,
 	issueLoyaltyCard,
 	updateLoyaltyPoints,
 	getGoogleObject
 } from 'sbcwallet'
 
-const biz = createBusiness({ name: 'SBC Coffee', pointsLabel: 'Beans' })
-await createLoyaltyProgram({ businessId: biz.id })
+const memberId = 'USER-123'
+
+const customer = createCustomerAccount({
+	businessId: biz.id,
+	fullName: 'Alice',
+	memberId
+})
+
+const card = await issueLoyaltyCard({
+	businessId: biz.id,
+	customerId: customer.id,
+	initialPoints: 10,
+	metadata: {
+		googleWallet: {
+			objectOverrides: {
+				linksModuleData: {
+					uris: [{ uri: 'https://example.com', description: 'Website' }]
+				}
+			}
+		}
+	}
+})
 
-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)
 ```
 
-⸻
+## Location-based surfacing and notifications
 
-## 🧠 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.
-```
+This SDK supports two related concepts:
 
-⸻
+1) Location-based surfacing (no server required)
+- Apple Wallet: setting `locations` and `relevantText` in pass.json can surface the pass on the lock screen when the user is near the business.
+- Google Wallet: setting `locations` on the class/object helps Wallet surface the pass contextually.
 
-## 🧩 Profiles
+2) Push-style notifications (server required)
+- Google Wallet supports sending a message via the `addMessage` API. Your system decides *when* to send the message (for example, after your app detects the user is near the business).
 
-### 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	
+```ts
+import { pushLoyaltyMessage } from 'sbcwallet'
 
-Switch profiles dynamically:
-```js
-await createChildTicket({ profile: 'healthcare', ... })
+await pushLoyaltyMessage({
+	cardId: card.id,
+	header: 'X',
+	body: 'You are nearby — show this card to earn points.',
+	messageType: 'TEXT_AND_NOTIFY'
+})
 ```
 
-⸻
-
-## 🔐 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)
-
-⸻
+## Demo server (multi-tenant)
 
-## ⚙️ 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
+npm run loyalty:server:multi
 ```
 
-⸻
+Open `http://localhost:5190`.
 
-## 🧾 License
+## Configuration
 
-Apache License 2.0
-© 2025 sbcwallet — open and extensible.
+For Google Wallet Save URLs to work on-device you must set:
+- `GOOGLE_ISSUER_ID`
+- `GOOGLE_SA_JSON`
 
-⸻
+For Apple Wallet signing, see APPLE_WALLET_SETUP.md.
 
-## 🤝 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
+## Development
 
-⸻
-
-## 🧭 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)
+npm run build
+npm test
+npm pack --dry-run
 ```
 
-⸻
-
-“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.js

@@ -27,26 +27,28 @@ export class AppleWalletAdapter {
             const template = this.mergeTemplates(baseTemplate, profileTemplate);
             // Apply pass data to template
             const populatedTemplate = this.populateTemplate(template, passData, profile, passType);
+            // Optional per-pass overrides via metadata (useful for per-business theming)
+            const appleWallet = passData?.metadata?.appleWallet || {};
             // Build pass props from populated template
             const passProps = {
                 serialNumber: passData.id,
-                description: populatedTemplate.description || 'sbcwallet Pass',
-                organizationName: populatedTemplate.organizationName || 'sbcwallet',
+                description: appleWallet.description || populatedTemplate.description || 'sbcwallet Pass',
+                organizationName: appleWallet.organizationName || populatedTemplate.organizationName || 'sbcwallet',
                 passTypeIdentifier: this.config.passTypeId,
                 teamIdentifier: this.config.teamId
             };
             // Add colors
-            if (populatedTemplate.backgroundColor) {
-                passProps.backgroundColor = populatedTemplate.backgroundColor;
+            if (appleWallet.backgroundColor || populatedTemplate.backgroundColor) {
+                passProps.backgroundColor = appleWallet.backgroundColor || populatedTemplate.backgroundColor;
             }
-            if (populatedTemplate.foregroundColor) {
-                passProps.foregroundColor = populatedTemplate.foregroundColor;
+            if (appleWallet.foregroundColor || populatedTemplate.foregroundColor) {
+                passProps.foregroundColor = appleWallet.foregroundColor || populatedTemplate.foregroundColor;
             }
-            if (populatedTemplate.labelColor) {
-                passProps.labelColor = populatedTemplate.labelColor;
+            if (appleWallet.labelColor || populatedTemplate.labelColor) {
+                passProps.labelColor = appleWallet.labelColor || populatedTemplate.labelColor;
             }
-            if (populatedTemplate.logoText) {
-                passProps.logoText = populatedTemplate.logoText;
+            if (appleWallet.logoText || populatedTemplate.logoText) {
+                passProps.logoText = appleWallet.logoText || populatedTemplate.logoText;
             }
             // Add barcodes
             if (populatedTemplate.barcodes && populatedTemplate.barcodes.length > 0) {
@@ -56,6 +58,11 @@ export class AppleWalletAdapter {
             if (populatedTemplate.generic) {
                 passProps.generic = populatedTemplate.generic;
             }
+            // Advanced passthrough: allow issuers to supply any PassKit fields.
+            // Example: webServiceURL, authenticationToken, appLaunchURL, userInfo, beacons, nfc, etc.
+            if (appleWallet.passOverrides && typeof appleWallet.passOverrides === 'object') {
+                Object.assign(passProps, appleWallet.passOverrides);
+            }
             // Create pass
             const pass = new PKPass({}, {
                 wwdr: this.config.wwdrPath,

package/dist/adapters/google.d.ts

@@ -13,6 +13,11 @@ export declare class GoogleWalletAdapter {
     private getFieldValue;
     private generateSaveUrl;
     private upsertInAPI;
+    addMessageToLoyaltyObject(loyaltyObjectId: string, message: {
+        header: string;
+        body: string;
+        messageType?: string;
+    }): Promise<void>;
     /**
      * Generate and add hero image with progress bar to the pass object
      *

package/dist/adapters/google.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { GoogleAuth } from 'google-auth-library';
 import { generateLogisticsHeroImage, generateHealthcareHeroImage } from '../utils/progress-image.js';
+import { logDebug, logWarn, logError } from '../utils/logger.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 export class GoogleWalletAdapter {
@@ -32,14 +33,14 @@ export class GoogleWalletAdapter {
                         await this.upsertInAPI('loyaltyClass', classPayload);
                     }
                     catch (error) {
-                        console.warn('⚠️  Google Wallet API loyaltyClass create/update failed');
-                        console.warn(error);
+                        logWarn('Google Wallet API loyaltyClass create/update failed');
+                        logWarn(error);
                     }
                 }
                 else {
-                    console.log('⚠️  No Google Auth - class not created in API (will not work on device)');
+                    logWarn('No Google Auth - class not created in API (will not work on device)');
                 }
-                console.log('Google Wallet Class:', JSON.stringify(classPayload, null, 2));
+                logDebug('Google Wallet Class:', JSON.stringify(classPayload, null, 2));
                 // Save URL is not applicable for classes.
                 return { object: classPayload, saveUrl: '' };
             }
@@ -85,20 +86,20 @@ export class GoogleWalletAdapter {
                 }
                 catch (error) {
                     // Keep going so we can still generate a signed Save URL for debugging/testing.
-                    console.warn('⚠️  Google Wallet API object create/update failed; continuing to Save URL generation');
-                    console.warn(error);
+                    logWarn('Google Wallet API object create/update failed; continuing to Save URL generation');
+                    logWarn(error);
                 }
             }
             else {
-                console.log('⚠️  No Google Auth - object not created in API (will not work on device)');
+                logWarn('No Google Auth - object not created in API (will not work on device)');
             }
             // Generate save URL with signed JWT
             // Prefer embedding the full object in the JWT payload so the Save URL can work
             // even if the object was not pre-created in the API.
             const saveUrl = await this.generateSaveUrl(populatedObject, isLoyalty ? 'loyaltyObjects' : 'genericObjects');
             // Log the object
-            console.log('Google Wallet Object:', JSON.stringify(populatedObject, null, 2));
-            console.log('Save URL:', saveUrl);
+            logDebug('Google Wallet Object:', JSON.stringify(populatedObject, null, 2));
+            logDebug('Save URL:', saveUrl);
             return {
                 object: populatedObject,
                 saveUrl
@@ -120,10 +121,16 @@ export class GoogleWalletAdapter {
             ...baseTemplate,
             ...profileTemplate,
             id: classId,
-            issuerName: profileTemplate.issuerName || googleWallet.issuerName || 'sbcwallet',
+            // Prefer business/program-provided metadata over template defaults.
+            issuerName: googleWallet.issuerName || profileTemplate.issuerName || baseTemplate.issuerName || 'sbcwallet',
             programName: passData.programName || googleWallet.programName || 'Loyalty',
             hexBackgroundColor: googleWallet.backgroundColor || baseTemplate.hexBackgroundColor || '#111827'
         };
+        // Geo locations (latitude/longitude pairs) for location-based surfacing.
+        const locations = googleWallet.locations || metadata.locations;
+        if (Array.isArray(locations) && locations.length > 0) {
+            payload.locations = locations;
+        }
         if (googleWallet.countryCode)
             payload.countryCode = googleWallet.countryCode;
         if (googleWallet.homepageUrl) {
@@ -280,7 +287,7 @@ export class GoogleWalletAdapter {
         const baseUrl = 'https://pay.google.com/gp/v/save';
         const objectId = passObject.id;
         if (!this.config.serviceAccountPath) {
-            console.warn('⚠️  No service account - returning unsigned URL (will not work)');
+            logWarn('No service account - returning unsigned URL (will not work)');
             return `${baseUrl}/${encodeURIComponent(objectId)}`;
         }
         try {
@@ -306,7 +313,7 @@ export class GoogleWalletAdapter {
             return `${baseUrl}/${token}`;
         }
         catch (error) {
-            console.error('Error generating signed JWT:', error);
+            logError('Error generating signed JWT:', error);
             return `${baseUrl}/${encodeURIComponent(objectId)}`;
         }
     }
@@ -324,12 +331,12 @@ export class GoogleWalletAdapter {
                 method: 'POST',
                 data: payload
             });
-            console.log(`✅ ${kind} created in Google Wallet API`);
+            logDebug(`✅ ${kind} created in Google Wallet API`);
         }
         catch (error) {
             if (error.response?.status === 409) {
                 // Object already exists, try to update it
-                console.log('ℹ️  Resource exists, updating...');
+                logDebug('ℹ️  Resource exists, updating...');
                 try {
                     const client = await this.auth.getClient();
                     const baseUrl = 'https://walletobjects.googleapis.com/walletobjects/v1';
@@ -340,19 +347,37 @@ export class GoogleWalletAdapter {
                         method: 'PUT',
                         data: payload
                     });
-                    console.log(`✅ ${kind} updated in Google Wallet API`);
+                    logDebug(`✅ ${kind} updated in Google Wallet API`);
                 }
                 catch (updateError) {
-                    console.error(`❌ Error updating ${kind}:`, updateError);
+                    logError(`❌ Error updating ${kind}:`, updateError);
                     throw updateError;
                 }
             }
             else {
-                console.error(`❌ Error creating ${kind}:`, error.response?.data || error.message);
+                logError(`❌ Error creating ${kind}:`, error.response?.data || error.message);
                 throw error;
             }
         }
     }
+    async addMessageToLoyaltyObject(loyaltyObjectId, message) {
+        if (!this.auth) {
+            throw new Error('Google Auth not initialized');
+        }
+        const client = await this.auth.getClient();
+        const baseUrl = 'https://walletobjects.googleapis.com/walletobjects/v1';
+        await client.request({
+            url: `${baseUrl}/loyaltyObject/${encodeURIComponent(loyaltyObjectId)}/addMessage`,
+            method: 'POST',
+            data: {
+                message: {
+                    header: message.header,
+                    body: message.body,
+                    messageType: message.messageType || 'TEXT_AND_NOTIFY'
+                }
+            }
+        });
+    }
     /**
      * Generate and add hero image with progress bar to the pass object
      *
@@ -381,11 +406,11 @@ export class GoogleWalletAdapter {
             // Ensure directory exists
             try {
                 await writeFile(imagePath, imageBuffer);
-                console.log(`✨ Hero image saved: ${imagePath}`);
+                logDebug(`✨ Hero image saved: ${imagePath}`);
             }
             catch (err) {
                 // Directory might not exist, that's OK - just skip for now
-                console.log(`ℹ️  Hero image generated (not uploaded - requires public URL)`);
+                logDebug('ℹ️  Hero image generated (not uploaded - requires public URL)');
             }
             // TODO: Upload to cloud storage and get public URL
             // For now, we'll skip adding the hero image to the pass object
@@ -410,10 +435,10 @@ export class GoogleWalletAdapter {
                 DISCHARGED: '#7ED321'
             };
             passObject.hexBackgroundColor = statusColors[passData.status] || '#4A90E2';
-            console.log(`✨ Dynamic color applied for status: ${passData.status} (${passObject.hexBackgroundColor})`);
+            logDebug(`✨ Dynamic color applied for status: ${passData.status} (${passObject.hexBackgroundColor})`);
         }
         catch (error) {
-            console.error('⚠️  Failed to generate hero image:', error);
+            logError('⚠️  Failed to generate hero image:', error);
             // Continue without hero image if generation fails
         }
     }
@@ -421,9 +446,9 @@ export class GoogleWalletAdapter {
         // Stub for creating a Google Wallet class
         // In a real implementation, this would call the Google Wallet API
         const classId = `${this.config.issuerId}.${profile.name}_${passType}`;
-        console.log(`Creating Google Wallet Class: ${classId}`);
-        console.log('Profile:', profile.name);
-        console.log('Type:', passType);
+        logDebug(`Creating Google Wallet Class: ${classId}`);
+        logDebug('Profile:', profile.name);
+        logDebug('Type:', passType);
         // This would normally make an API call to:
         // POST https://walletobjects.googleapis.com/walletobjects/v1/genericClass
     }

package/dist/api/unified.d.ts

@@ -1,4 +1,4 @@
-import type { CreateParentInput, CreateChildInput, CreateBusinessInput, CreateCustomerAccountInput, CreateLoyaltyProgramInput, IssueLoyaltyCardInput, UpdateLoyaltyPointsInput, LoyaltyBusiness, LoyaltyCustomerAccount, ParentPassData, ChildPassData, PassData, PassStatus, ProfileType, ProfileConfig, PassGenerationResult } from '../types.js';
+import type { CreateParentInput, CreateChildInput, CreateBusinessInput, CreateCustomerAccountInput, CreateLoyaltyProgramInput, IssueLoyaltyCardInput, UpdateLoyaltyPointsInput, PushLoyaltyMessageInput, LoyaltyBusiness, LoyaltyCustomerAccount, ParentPassData, ChildPassData, PassData, PassStatus, ProfileType, ProfileConfig, PassGenerationResult } from '../types.js';
 /**
  * Get a profile by name
  */
@@ -31,6 +31,17 @@ export declare function issueLoyaltyCard(input: IssueLoyaltyCardInput): Promise<
  * Update points on a loyalty card.
  */
 export declare function updateLoyaltyPoints(input: UpdateLoyaltyPointsInput): Promise<PassData>;
+/**
+ * Send a message to a Google Wallet loyalty object.
+ *
+ * Notes:
+ * - This uses the Google Wallet API addMessage endpoint (requires service account credentials).
+ * - Location-based surfacing is controlled by the pass locations; your system decides WHEN to send messages.
+ */
+export declare function pushLoyaltyMessage(input: PushLoyaltyMessageInput): Promise<{
+    ok: true;
+    objectId: string;
+}>;
 /**
  * Create a parent schedule (PES or AppointmentBatch)
  */