@doorstepai/dropoff-sdk-capacitor 1.0.0

package/DoorstepaiDropoffSdkCapacitor.podspec

@@ -0,0 +1,22 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'DoorstepaiDropoffSdkCapacitor'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Plugin/**/*.{swift,h,m}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+  s.vendored_frameworks = 'ios/DoorstepDropoffSDK.xcframework'
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386'
+  }
+end

package/LICENSE

@@ -0,0 +1,20 @@
+Proprietary Software License
+
+Copyright (c) 2024 Doing Doorstep Better, Inc.. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary and confidential. 
+The Software is protected by copyright laws and international copyright treaties, as well as other 
+intellectual property laws and treaties.
+
+No part of this Software may be reproduced, distributed, or transmitted in any form or by any means, 
+including photocopying, recording, or other electronic or mechanical methods, without the prior 
+written permission of DoorstepAI.
+
+Unauthorized copying, modification, distribution, or use of this Software, via any medium, is 
+strictly prohibited and will be prosecuted to the maximum extent possible under the law.
+
+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

@@ -0,0 +1,401 @@
+# DoorstepAI Dropoff SDK for Capacitor
+
+The `@doorstepai/dropoff-sdk-capacitor` package provides Capacitor bindings to DoorstepAI's Dropoff SDK, enabling delivery tracking functionality through the Capacitor bridge and native platform integration.
+
+## 📦 Installation
+
+Add the SDK to your Capacitor app:
+
+```bash
+npm install @doorstepai/dropoff-sdk-capacitor
+npx cap sync
+```
+
+---
+
+## 🔌 Imports
+
+In your TypeScript/JavaScript code, import the SDK:
+
+```ts
+import {
+  DoorstepAIDropoffSDK,
+  AddressType,
+} from '@doorstepai/dropoff-sdk-capacitor';
+```
+
+---
+
+## 🗺️ AddressType
+
+A helper interface to represent a structured address for deliveries:
+
+```ts
+interface AddressType {
+  streetNumber: string;
+  route: string;
+  subPremise?: string;          // optional
+  locality: string;
+  administrativeAreaLevel1: string;
+  postalCode: string;
+}
+```
+
+---
+
+## 🚚 DoorstepAI API
+
+All calls go through the Capacitor bridge under the plugin name `DoorstepAIDropoffSDK`. Be sure to `await` each call and wrap in `try/catch`.
+
+### `init` (Android Only)
+
+Initializes the native SDK on Android. This is automatically called by `bootstrapDoorstepAI`, so you typically don't need to call this directly.
+
+```ts
+// Android only: call once before any other API methods
+await DoorstepAIDropoffSDK.init({
+  notificationTitle: 'Delivery in progress',  // optional
+  notificationText: 'Tap to return to the app', // optional
+});
+```
+
+### `setApiKey`
+
+Set your DoorstepAI API key. This should be called after initialization. Again, you typically don't need to call this directly.
+
+```ts
+await DoorstepAIDropoffSDK.setApiKey({ key: 'YOUR_API_KEY' });
+```
+
+### `startDeliveryByPlaceID`
+
+Begin a delivery session using a Google Place ID:
+
+```ts
+await DoorstepAIDropoffSDK.startDeliveryByPlaceID({
+  placeID: 'destination_place_id',
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `startDeliveryByPlusCode`
+
+Begin a delivery via Google Plus Code:
+
+```ts
+await DoorstepAIDropoffSDK.startDeliveryByPlusCode({
+  plusCode: 'destination_plus_code',
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `startDeliveryByAddress`
+
+Begin a delivery with a structured address:
+
+```ts
+await DoorstepAIDropoffSDK.startDeliveryByAddress({
+  address: {
+    streetNumber: '123',
+    route: 'Main St',
+    subPremise: 'Apt 4B',
+    locality: 'New York',
+    administrativeAreaLevel1: 'NY',
+    postalCode: '10001',
+  },
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `startDeliveryByAddressString`
+
+Begin a delivery with a free-form address string:
+
+```ts
+await DoorstepAIDropoffSDK.startDeliveryByAddressString({
+  address: '123 Main St, Apt 4B, New York, NY 10001',
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `startDeliveryByLatLng`
+
+Begin a delivery with raw coordinates and an optional sub-unit:
+
+```ts
+await DoorstepAIDropoffSDK.startDeliveryByLatLng({
+  latitude: 40.7128,
+  longitude: -74.006,
+  subUnit: 'Apt 4B',           // optional
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+> All `startDelivery*` methods accept an optional `timeoutSeconds` to bound the
+> destination resolution step. The address-based methods also accept an optional
+> `coordinates: { lat, lng }` hint to skip geocoding when you already have it.
+
+### `newEvent`
+
+Send a delivery event (`taking_pod`, `pod_captured`, etc.):
+
+```ts
+await DoorstepAIDropoffSDK.newEvent({
+  eventName: 'taking_pod',
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `markDropoff`
+
+Mark the dropoff outcome for the active delivery as either proof-of-delivery
+(`pod`) or non-POD (`non_pod`):
+
+```ts
+await DoorstepAIDropoffSDK.markDropoff({
+  deliveryId: 'unique_delivery_id',
+  dropoffType: 'pod', // or 'non_pod'
+});
+```
+
+### `stopDelivery`
+
+End the delivery session:
+
+```ts
+await DoorstepAIDropoffSDK.stopDelivery({
+  deliveryId: 'unique_delivery_id',
+});
+```
+
+### `requestPermissions` / `checkPermissions`
+
+Request or inspect the runtime permissions the SDK uses (foreground location
+and activity/motion). `bootstrapDoorstepAI` calls `requestPermissions` for
+you; call these directly only if you need finer-grained control.
+
+```ts
+const status = await DoorstepAIDropoffSDK.requestPermissions({
+  permissions: ['location', 'activity'], // omit to request all
+});
+// status.location, status.activity → 'granted' | 'denied' | 'prompt' | 'prompt-with-rationale'
+
+const current = await DoorstepAIDropoffSDK.checkPermissions();
+```
+
+---
+
+## 📱 Bootstrap Helper: `bootstrapDoorstepAI`
+
+The `bootstrapDoorstepAI` recipe handles SDK initialization, API key setting, and permission requests in one call. Run it once at app startup, before any `startDelivery*` calls.
+
+```ts
+import { DoorstepAIDropoffSDK } from '@doorstepai/dropoff-sdk-capacitor';
+
+async function bootstrapDoorstepAI(opts: {
+  apiKey: string;
+  notificationTitle?: string;
+  notificationText?: string;
+}) {
+  await DoorstepAIDropoffSDK.init({
+    notificationTitle: opts.notificationTitle,
+    notificationText: opts.notificationText,
+  });
+  await DoorstepAIDropoffSDK.setApiKey({ key: opts.apiKey });
+  await DoorstepAIDropoffSDK.requestPermissions({
+    permissions: ['location', 'activity'],
+  });
+}
+
+// Call once at app startup:
+await bootstrapDoorstepAI({
+  apiKey: 'YOUR_API_KEY',
+  notificationTitle: 'Tracking Delivery',
+  notificationText: 'Tap to return',
+});
+```
+
+### What `bootstrapDoorstepAI` Does Automatically:
+
+1. **Initialization**: Calls `DoorstepAIDropoffSDK.init()` on Android (no-op on iOS).
+2. **API Key Setting**: Calls `DoorstepAIDropoffSDK.setApiKey()` with the provided key.
+3. **Permission Handling**: Requests location and activity recognition permissions.
+4. **Platform Support**: Behaves correctly on each platform — the plugin transparently mounts its hidden host view on iOS when the API key is set.
+
+---
+
+## ✅ Best Practices
+
+- Run `bootstrapDoorstepAI` once at app startup to handle automatic initialization.
+- Wrap all SDK calls in `try/catch` for robust error handling.
+- Keep your `deliveryId` unique per session.
+- Securely store your API key; don't hardcode it in production.
+- Use the same `deliveryId` for all operations within a single delivery session.
+
+---
+
+## 🔧 Platform-Specific Setup
+
+### Android
+
+Add the following permissions to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+
+    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
+
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+
+    <uses-feature android:name="android.hardware.sensor.accelerometer" />
+    <uses-feature android:name="android.hardware.sensor.gyroscope" />
+    <uses-feature android:name="android.hardware.sensor.barometer" />
+    <uses-feature android:name="android.hardware.sensor.compass" />
+    <uses-feature android:name="android.hardware.sensor.proximity" />
+```
+
+### iOS
+
+Add usage descriptions to `ios/App/App/Info.plist`:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>This app requires access to your location for enhanced delivery intelligence</string>
+
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>This app requires access to your location for enhanced delivery intelligence</string>
+
+<key>NSMotionUsageDescription</key>
+<string>This app requires access to motion data for enhanced delivery intelligence</string>
+
+<key>UIBackgroundModes</key>
+<array>
+    <string>location</string>
+</array>
+
+```
+
+---
+
+## 🧪 Example App
+
+A working Capacitor + Next.js + Ionic example app lives in `example/`. It
+exposes one card per public SDK method so you can drive a delivery end-to-end.
+
+### Setup
+
+```bash
+cd example
+cp .env.example .env.local        # set NEXT_PUBLIC_DOORSTEPAI_API_KEY
+npm install
+npx cap add ios                   # first time only
+npx cap add android               # first time only
+```
+
+### Build & run
+
+```bash
+# from example/
+npm run build && npm run sync && npm run ios       # or: npm run android
+```
+
+### Permissions after first launch
+
+iOS only shows each permission prompt **once per install**. If the user
+denied (or the prompt didn't appear because an earlier build was missing the
+required `Info.plist` keys), grant manually:
+
+- **iOS** — Settings → Privacy & Security → Location Services → DoorstepAI
+  Dropoff Example → "While Using" or "Always" (Always is required for
+  background tracking; the plugin doesn't request it directly). Then Motion &
+  Fitness → toggle on.
+- **Android** — Settings → Apps → DoorstepAI Dropoff Example → Permissions
+  → enable Location and Physical activity.
+
+To reset for testing, delete the app and reinstall.
+
+---
+
+## 🧪 Debugging
+
+- Check your debug console for errors thrown by `try/catch` blocks.
+- On Android, verify notification permissions and channel configuration.
+- Use the example app in the `example/` directory to test functionality.
+
+---
+
+## 📋 Complete Example
+
+```ts
+import {
+  DoorstepAIDropoffSDK,
+  AddressType,
+} from '@doorstepai/dropoff-sdk-capacitor';
+
+async function bootstrapDoorstepAI(opts: {
+  apiKey: string;
+  notificationTitle?: string;
+  notificationText?: string;
+}) {
+  await DoorstepAIDropoffSDK.init({
+    notificationTitle: opts.notificationTitle,
+    notificationText: opts.notificationText,
+  });
+  await DoorstepAIDropoffSDK.setApiKey({ key: opts.apiKey });
+  await DoorstepAIDropoffSDK.requestPermissions({
+    permissions: ['location', 'activity'],
+  });
+}
+
+let currentDeliveryId: string | null = null;
+
+async function startDelivery() {
+  try {
+    const deliveryId = `delivery_${Date.now()}`;
+
+    await DoorstepAIDropoffSDK.startDeliveryByAddress({
+      address: {
+        streetNumber: '123',
+        route: 'Main St',
+        locality: 'New York',
+        administrativeAreaLevel1: 'NY',
+        postalCode: '10001',
+      },
+      deliveryId,
+    });
+
+    currentDeliveryId = deliveryId;
+  } catch (e) {
+    console.error('Error starting delivery:', e);
+  }
+}
+
+async function stopDelivery() {
+  if (currentDeliveryId !== null) {
+    try {
+      await DoorstepAIDropoffSDK.stopDelivery({ deliveryId: currentDeliveryId });
+      currentDeliveryId = null;
+    } catch (e) {
+      console.error('Error stopping delivery:', e);
+    }
+  }
+}
+
+// At app startup:
+await bootstrapDoorstepAI({
+  apiKey: 'YOUR_API_KEY',
+  notificationTitle: 'Delivery Update',
+  notificationText: 'Your driver is approaching',
+});
+```

package/android/build.gradle

@@ -0,0 +1,48 @@
+ext {
+    capacitorAndroidVersion = project.hasProperty('capacitorAndroidVersion') ? rootProject.ext.capacitorAndroidVersion : '7.0.0'
+}
+
+buildscript {
+    ext.kotlin_version = '1.9.25'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace 'ai.doorstep.dropoffsdk.capacitor'
+    compileSdk project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.targetSdkVersion : 35
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_21.toString()
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "androidx.appcompat:appcompat:1.6.1"
+    implementation "com.capacitorjs:core:$capacitorAndroidVersion"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
+    implementation "ai.doorstep.com:doorstepai-dropoff-sdk:2.0.6"
+    testImplementation "org.junit.jupiter:junit-jupiter-api:5.10.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>