sbcwallet 0.0.2 → 0.0.3

package/README.md

@@ -1,191 +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.
-
-⸻
-
-## ✨ 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
+## Install
 
 ```sh
 npm install sbcwallet
 ```
 
-```js
+## Quickstart (Loyalty)
 
-import { createParentSchedule, createChildTicket, getPkpassBuffer } from '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.
 
-// 1️⃣ Create a parent PES schedule
-const pes = await createParentSchedule({
-  profile: 'logistics',
-  programName: 'Morning Yard Veracruz',
-  site: 'Patio Gate 3'
-})
+### Define a business (per-tenant theme) and create its program
 
-// 2️⃣ Claim a child Transport Order
-const to = await createChildTicket({
-  parentId: pes.id,
-  plate: 'ABC123A',
-  carrier: 'Transportes Golfo'
+```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' }
+			}
+		}
+	}
 })
 
-// 3️⃣ Generate Apple Wallet pass
-const buf = await getPkpassBuffer('child', to)
-await fs.promises.writeFile('ticket.pkpass', buf)
+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'
+})
 ```
 
-## 🎁 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', pointsLabel: 'points' })
-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)
 ```
 
-⸻
-
-## 🧠 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
+## Location-based surfacing and notifications
 
-### Logistics (default)
+This SDK supports two related concepts:
 
-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	
+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.
 
-### Healthcare (reference)
+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).
 
-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)
  */

package/dist/api/unified.js

@@ -1,6 +1,7 @@
-import { CreateParentInputSchema, CreateChildInputSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema } from '../types.js';
+import { CreateParentInputSchema, CreateChildInputSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema, PushLoyaltyMessageInputSchema } from '../types.js';
 import { AppleWalletAdapter } from '../adapters/apple.js';
 import { GoogleWalletAdapter } from '../adapters/google.js';
+import { logWarn } from '../utils/logger.js';
 import logisticsProfile from '../profiles/logistics/index.js';
 import healthcareProfile from '../profiles/healthcare/index.js';
 import loyaltyProfile from '../profiles/loyalty/index.js';
@@ -78,6 +79,7 @@ export function createBusiness(input) {
         name: validated.name,
         programName: validated.programName || `${validated.name} Loyalty`,
         pointsLabel: validated.pointsLabel || 'Points',
+        wallet: validated.wallet,
         createdAt: now,
         updatedAt: now
     };
@@ -122,6 +124,38 @@ export async function createLoyaltyProgram(input) {
     if (!business) {
         throw new Error(`Business not found: ${validated.businessId}`);
     }
+    const businessWallet = business.wallet || {};
+    const inputMetadata = (validated.metadata || {});
+    const mergedGoogleWallet = {
+        ...(businessWallet.googleWallet || {}),
+        ...(inputMetadata.googleWallet || {}),
+        locations: validated.locations,
+        countryCode: validated.countryCode,
+        homepageUrl: validated.homepageUrl
+    };
+    // If caller didn't set issuerName explicitly, default to the business name
+    // so the card shows the tenant brand instead of template defaults.
+    if (!mergedGoogleWallet.issuerName) {
+        mergedGoogleWallet.issuerName = business.name;
+    }
+    const mergedAppleWallet = {
+        ...(businessWallet.appleWallet || {}),
+        ...(inputMetadata.appleWallet || {})
+    };
+    // Apple Wallet: location-based surfacing is controlled via pass.json fields.
+    // We attach them at the program level so issued cards inherit the behavior.
+    if (validated.locations && Array.isArray(validated.locations) && validated.locations.length > 0) {
+        mergedAppleWallet.passOverrides ||= {};
+        if (!mergedAppleWallet.passOverrides.locations) {
+            mergedAppleWallet.passOverrides.locations = validated.locations;
+        }
+    }
+    if (validated.relevantText) {
+        mergedAppleWallet.passOverrides ||= {};
+        if (!mergedAppleWallet.passOverrides.relevantText) {
+            mergedAppleWallet.passOverrides.relevantText = validated.relevantText;
+        }
+    }
     const program = await createParentSchedule({
         id: validated.programId,
         profile: 'loyalty',
@@ -132,12 +166,8 @@ export async function createLoyaltyProgram(input) {
             businessId: business.id,
             businessName: business.name,
             pointsLabel: business.pointsLabel,
-            googleWallet: {
-                ...validated.metadata?.googleWallet,
-                locations: validated.locations,
-                countryCode: validated.countryCode,
-                homepageUrl: validated.homepageUrl
-            }
+            googleWallet: mergedGoogleWallet,
+            appleWallet: mergedAppleWallet
         }
     });
     business.loyaltyProgramId = program.id;
@@ -164,6 +194,7 @@ export async function issueLoyaltyCard(input) {
     }
     const program = passStore.get(business.loyaltyProgramId);
     const programGoogleWallet = program && program.type === 'parent' ? program.metadata?.googleWallet : undefined;
+    const programAppleWallet = program && program.type === 'parent' ? program.metadata?.appleWallet : undefined;
     const card = await createChildTicket({
         id: validated.cardId,
         profile: 'loyalty',
@@ -180,6 +211,10 @@ export async function issueLoyaltyCard(input) {
             googleWallet: {
                 ...(programGoogleWallet || {}),
                 ...(validated.metadata?.googleWallet || {})
+            },
+            appleWallet: {
+                ...(programAppleWallet || {}),
+                ...(validated.metadata?.appleWallet || {})
             }
         }
     });
@@ -214,6 +249,25 @@ export async function updateLoyaltyPoints(input) {
     passStore.set(pass.id, pass);
     return pass;
 }
+/**
+ * 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 async function pushLoyaltyMessage(input) {
+    const validated = PushLoyaltyMessageInputSchema.parse(input);
+    const issuerId = process.env.GOOGLE_ISSUER_ID || 'test-issuer';
+    const objectId = validated.objectId || `${issuerId}.${validated.cardId}`;
+    const adapter = new GoogleWalletAdapter();
+    await adapter.addMessageToLoyaltyObject(objectId, {
+        header: validated.header,
+        body: validated.body,
+        messageType: validated.messageType
+    });
+    return { ok: true, objectId };
+}
 /**
  * Create a parent schedule (PES or AppointmentBatch)
  */
@@ -358,7 +412,7 @@ export async function generatePass(passData, options = { includeApple: true, inc
             result.applePkpass = await getPkpassBuffer(passType, passData);
         }
         catch (error) {
-            console.warn('Failed to generate Apple Wallet pass:', error);
+            logWarn('Failed to generate Apple Wallet pass:', error);
         }
     }
     if (options.includeGoogle) {
@@ -368,7 +422,7 @@ export async function generatePass(passData, options = { includeApple: true, inc
             result.googleSaveUrl = googleResult.saveUrl;
         }
         catch (error) {
-            console.warn('Failed to generate Google Wallet object:', error);
+            logWarn('Failed to generate Google Wallet object:', error);
         }
     }
     return result;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { createParentSchedule, createChildTicket, updatePassStatus, createBusiness, getBusiness, createCustomerAccount, getCustomerAccount, createLoyaltyProgram, issueLoyaltyCard, updateLoyaltyPoints, getPkpassBuffer, getGoogleObject, listProfiles, getProfile, getPass, generatePass } from './api/unified.js';
+export { createParentSchedule, createChildTicket, updatePassStatus, createBusiness, getBusiness, createCustomerAccount, getCustomerAccount, createLoyaltyProgram, issueLoyaltyCard, updateLoyaltyPoints, pushLoyaltyMessage, getPkpassBuffer, getGoogleObject, listProfiles, getProfile, getPass, generatePass } from './api/unified.js';
 export { AppleWalletAdapter } from './adapters/apple.js';
 export { GoogleWalletAdapter } from './adapters/google.js';
 export { default as logisticsProfile } from './profiles/logistics/index.js';
 export { default as healthcareProfile } from './profiles/healthcare/index.js';
 export { default as loyaltyProfile } from './profiles/loyalty/index.js';
-export type { ProfileType, PassStatus, LogisticsStatus, HealthcareStatus, LoyaltyStatus, GeoLocation, TimeWindow, BasePassData, ParentPassData, ChildPassData, PassData, CreateParentInput, CreateChildInput, LoyaltyBusiness, LoyaltyCustomerAccount, CreateBusinessInput, CreateCustomerAccountInput, CreateLoyaltyProgramInput, IssueLoyaltyCardInput, UpdateLoyaltyPointsInput, ApplePassConfig, ApplePassField, ApplePassTemplate, GooglePassConfig, GoogleTextField, GooglePassClass, GooglePassObject, ProfileFieldMap, ProfileConfig, PassGenerationResult } from './types.js';
-export { CreateParentInputSchema, CreateChildInputSchema, TimeWindowSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema } from './types.js';
+export type { ProfileType, PassStatus, LogisticsStatus, HealthcareStatus, LoyaltyStatus, GeoLocation, TimeWindow, BasePassData, ParentPassData, ChildPassData, PassData, CreateParentInput, CreateChildInput, LoyaltyBusiness, LoyaltyCustomerAccount, CreateBusinessInput, CreateCustomerAccountInput, CreateLoyaltyProgramInput, IssueLoyaltyCardInput, UpdateLoyaltyPointsInput, PushLoyaltyMessageInput, ApplePassConfig, ApplePassField, ApplePassTemplate, GooglePassConfig, GoogleTextField, GooglePassClass, GooglePassObject, ProfileFieldMap, ProfileConfig, PassGenerationResult } from './types.js';
+export { CreateParentInputSchema, CreateChildInputSchema, TimeWindowSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema, PushLoyaltyMessageInputSchema } from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 // Main exports
-export { createParentSchedule, createChildTicket, updatePassStatus, createBusiness, getBusiness, createCustomerAccount, getCustomerAccount, createLoyaltyProgram, issueLoyaltyCard, updateLoyaltyPoints, getPkpassBuffer, getGoogleObject, listProfiles, getProfile, getPass, generatePass } from './api/unified.js';
+export { createParentSchedule, createChildTicket, updatePassStatus, createBusiness, getBusiness, createCustomerAccount, getCustomerAccount, createLoyaltyProgram, issueLoyaltyCard, updateLoyaltyPoints, pushLoyaltyMessage, getPkpassBuffer, getGoogleObject, listProfiles, getProfile, getPass, generatePass } from './api/unified.js';
 // Adapter exports
 export { AppleWalletAdapter } from './adapters/apple.js';
 export { GoogleWalletAdapter } from './adapters/google.js';
@@ -8,4 +8,4 @@ export { default as logisticsProfile } from './profiles/logistics/index.js';
 export { default as healthcareProfile } from './profiles/healthcare/index.js';
 export { default as loyaltyProfile } from './profiles/loyalty/index.js';
 // Schema exports
-export { CreateParentInputSchema, CreateChildInputSchema, TimeWindowSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema } from './types.js';
+export { CreateParentInputSchema, CreateChildInputSchema, TimeWindowSchema, CreateBusinessInputSchema, CreateCustomerAccountInputSchema, CreateLoyaltyProgramInputSchema, IssueLoyaltyCardInputSchema, UpdateLoyaltyPointsInputSchema, PushLoyaltyMessageInputSchema } from './types.js';

package/dist/types.d.ts

@@ -154,6 +154,10 @@ export interface LoyaltyBusiness {
     programName: string;
     pointsLabel: string;
     loyaltyProgramId?: string;
+    wallet?: {
+        googleWallet?: Record<string, any>;
+        appleWallet?: Record<string, any>;
+    };
     createdAt: string;
     updatedAt: string;
 }
@@ -170,16 +174,34 @@ export declare const CreateBusinessInputSchema: z.ZodObject<{
     name: z.ZodString;
     programName: z.ZodOptional<z.ZodString>;
     pointsLabel: z.ZodOptional<z.ZodString>;
+    wallet: z.ZodOptional<z.ZodObject<{
+        googleWallet: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        appleWallet: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        googleWallet?: Record<string, any> | undefined;
+        appleWallet?: Record<string, any> | undefined;
+    }, {
+        googleWallet?: Record<string, any> | undefined;
+        appleWallet?: Record<string, any> | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     id?: string | undefined;
     programName?: string | undefined;
     pointsLabel?: string | undefined;
+    wallet?: {
+        googleWallet?: Record<string, any> | undefined;
+        appleWallet?: Record<string, any> | undefined;
+    } | undefined;
 }, {
     name: string;
     id?: string | undefined;
     programName?: string | undefined;
     pointsLabel?: string | undefined;
+    wallet?: {
+        googleWallet?: Record<string, any> | undefined;
+        appleWallet?: Record<string, any> | undefined;
+    } | undefined;
 }>;
 export type CreateBusinessInput = z.infer<typeof CreateBusinessInputSchema>;
 export declare const CreateCustomerAccountInputSchema: z.ZodObject<{
@@ -214,6 +236,7 @@ export declare const CreateLoyaltyProgramInputSchema: z.ZodObject<{
         latitude: number;
         longitude: number;
     }>, "many">>;
+    relevantText: z.ZodOptional<z.ZodString>;
     countryCode: z.ZodOptional<z.ZodString>;
     homepageUrl: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -227,6 +250,7 @@ export declare const CreateLoyaltyProgramInputSchema: z.ZodObject<{
         latitude: number;
         longitude: number;
     }[] | undefined;
+    relevantText?: string | undefined;
     countryCode?: string | undefined;
     homepageUrl?: string | undefined;
 }, {
@@ -239,6 +263,7 @@ export declare const CreateLoyaltyProgramInputSchema: z.ZodObject<{
         latitude: number;
         longitude: number;
     }[] | undefined;
+    relevantText?: string | undefined;
     countryCode?: string | undefined;
     homepageUrl?: string | undefined;
 }>;
@@ -285,6 +310,38 @@ export declare const UpdateLoyaltyPointsInputSchema: z.ZodEffects<z.ZodObject<{
     delta?: number | undefined;
 }>;
 export type UpdateLoyaltyPointsInput = z.infer<typeof UpdateLoyaltyPointsInputSchema>;
+export declare const PushLoyaltyMessageInputSchema: z.ZodEffects<z.ZodObject<{
+    cardId: z.ZodOptional<z.ZodString>;
+    objectId: z.ZodOptional<z.ZodString>;
+    header: z.ZodString;
+    body: z.ZodString;
+    messageType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    header: string;
+    body: string;
+    cardId?: string | undefined;
+    objectId?: string | undefined;
+    messageType?: string | undefined;
+}, {
+    header: string;
+    body: string;
+    cardId?: string | undefined;
+    objectId?: string | undefined;
+    messageType?: string | undefined;
+}>, {
+    header: string;
+    body: string;
+    cardId?: string | undefined;
+    objectId?: string | undefined;
+    messageType?: string | undefined;
+}, {
+    header: string;
+    body: string;
+    cardId?: string | undefined;
+    objectId?: string | undefined;
+    messageType?: string | undefined;
+}>;
+export type PushLoyaltyMessageInput = z.infer<typeof PushLoyaltyMessageInputSchema>;
 export type GeoLocation = {
     latitude: number;
     longitude: number;

package/dist/types.js

@@ -40,7 +40,12 @@ export const CreateBusinessInputSchema = z.object({
     id: z.string().min(1).optional(),
     name: z.string().min(1),
     programName: z.string().min(1).optional(),
-    pointsLabel: z.string().min(1).optional()
+    pointsLabel: z.string().min(1).optional(),
+    // Per-business theming / design knobs (optional)
+    wallet: z.object({
+        googleWallet: z.record(z.any()).optional(),
+        appleWallet: z.record(z.any()).optional()
+    }).optional()
 });
 export const CreateCustomerAccountInputSchema = z.object({
     id: z.string().min(1).optional(),
@@ -59,6 +64,8 @@ export const CreateLoyaltyProgramInputSchema = z.object({
         latitude: z.number().min(-90).max(90),
         longitude: z.number().min(-180).max(180)
     })).optional(),
+    // Apple Wallet: text shown when the pass becomes relevant (e.g., near a location)
+    relevantText: z.string().min(1).optional(),
     countryCode: z.string().length(2).optional(),
     homepageUrl: z.string().url().optional(),
     metadata: z.record(z.any()).optional()
@@ -78,3 +85,12 @@ export const UpdateLoyaltyPointsInputSchema = z.object({
 }).refine(v => v.setPoints !== undefined || v.delta !== undefined, {
     message: 'Provide either setPoints or delta'
 });
+export const PushLoyaltyMessageInputSchema = z.object({
+    cardId: z.string().min(1).optional(),
+    objectId: z.string().min(1).optional(),
+    header: z.string().min(1),
+    body: z.string().min(1),
+    messageType: z.string().min(1).optional()
+}).refine(v => v.cardId !== undefined || v.objectId !== undefined, {
+    message: 'Provide either cardId or objectId'
+});

package/dist/utils/logger.d.ts

@@ -0,0 +1,4 @@
+export declare function logDebug(...args: unknown[]): void;
+export declare function logInfo(...args: unknown[]): void;
+export declare function logWarn(...args: unknown[]): void;
+export declare function logError(...args: unknown[]): void;

package/dist/utils/logger.js

@@ -0,0 +1,24 @@
+const isTestEnv = process.env.NODE_ENV === 'test' ||
+    process.env.VITEST === 'true' ||
+    process.env.VITEST === '1';
+const isDebugEnabled = /^(1|true|yes)$/i.test(process.env.SBCWALLET_DEBUG || '');
+export function logDebug(...args) {
+    if (!isDebugEnabled)
+        return;
+    console.log(...args);
+}
+export function logInfo(...args) {
+    if (!isDebugEnabled)
+        return;
+    console.log(...args);
+}
+export function logWarn(...args) {
+    if (isTestEnv && !isDebugEnabled)
+        return;
+    console.warn(...args);
+}
+export function logError(...args) {
+    if (isTestEnv && !isDebugEnabled)
+        return;
+    console.error(...args);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbcwallet",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Unified Wallet-Pass SDK for Real-World Credentials",
   "type": "module",
   "sideEffects": false,
@@ -31,7 +31,8 @@
     "publish:npm": "npm publish",
     "loyalty:issue": "npm run build && node examples/loyalty-google-issue.js",
     "loyalty:server": "npm run build && node examples/loyalty-admin-server.js",
-    "loyalty:server:fixed": "npm run build && node examples/loyalty-fixed-card-server.js"
+    "loyalty:server:fixed": "npm run build && node examples/loyalty-fixed-card-server.js",
+    "loyalty:server:multi": "npm run build && node examples/loyalty-multi-tenant-server.js"
   },
   "keywords": [
     "wallet",