@oblongmedulla/homebridge-pawport 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oblongmedulla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# homebridge-pawport
+
+[![npm](https://img.shields.io/npm/v/homebridge-pawport)](https://www.npmjs.com/package/homebridge-pawport)
+[![npm](https://img.shields.io/npm/dt/homebridge-pawport)](https://www.npmjs.com/package/homebridge-pawport)
+
+A [Homebridge](https://homebridge.io) plugin that exposes your [Pawport](https://pawport.com) smart pet door as a **Lock** in Apple Home. Lock and unlock your pet door from the Home app, Siri, or automations.
+
+Supports **multiple doors** on a single account.
+
+---
+
+## Installation
+
+### Via Homebridge UI (recommended)
+Search for `homebridge-pawport` in the Homebridge plugin search and click Install.
+
+### Manual
+```bash
+npm install -g homebridge-pawport
+```
+
+---
+
+## Configuration
+
+After installing, go to the **Plugins** tab in Homebridge UI, find `homebridge-pawport`, and click **Settings**. Add one entry per door with:
+
+| Field | Description |
+|-------|-------------|
+| **Door Name** | Whatever you want to call it in Apple Home (e.g. "Dog Door") |
+| **Auth Token** | Your `x-auth-token` from the Pawport app (see below) |
+| **Door ID** | The UUID of your door (see below) |
+
+### Manual config.json example
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "PawportPlatform",
+      "name": "Pawport",
+      "doors": [
+        {
+          "name": "Dog Door",
+          "authToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "doorID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+        },
+        {
+          "name": "Cat Flap",
+          "authToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "doorID": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Finding Your Credentials
+
+You'll need to intercept your Pawport app's network traffic once to grab your `authToken` and `doorID`. Here's how:
+
+### What you need
+- An iPhone with the Pawport app installed
+- [Proxyman](https://apps.apple.com/us/app/proxyman-network-debug-tool/id1551292695) (free) or [Stream](https://apps.apple.com/us/app/stream-http-debugging-proxy/id1312141691) (~$4.99) from the App Store
+
+### Steps
+
+1. Install Proxyman or Stream on your iPhone
+2. Follow the in-app instructions to install the SSL certificate (Settings → trust the cert)
+3. Start capturing traffic
+4. Open the Pawport app, log in, and lock/unlock the door once
+5. Stop capture and filter by `api.app.pawport.com`
+6. Tap on a **sendDoorCommand** request
+7. View the **Request** tab / Raw headers
+
+You're looking for:
+- **`x-auth-token`** header → this is your `authToken`
+- **`doorID`** field in the request body → this is your `doorID`
+
+---
+
+## How It Works
+
+This plugin communicates with the Pawport cloud API using the same GraphQL endpoint as the official iOS app. The door appears as a **Lock Mechanism** in HomeKit, which means you can:
+
+- Lock / unlock from the Home app
+- Use Siri ("Hey Siri, lock the dog door")
+- Create automations (e.g. lock at sunset, unlock at 7am)
+- Include it in Home scenes
+
+> **Note:** This plugin is not affiliated with or endorsed by Pawport. Use at your own risk.
+
+---
+
+## Troubleshooting
+
+**Door shows as "No Response"**
+- Check that your `authToken` is correct and hasn't expired
+- Make sure your Homebridge server has internet access
+
+**Command fails silently**
+- Check the Homebridge logs for error details
+- Try locking/unlocking from the Pawport app to confirm the door is online
+
+---
+
+## Contributing
+
+Pull requests welcome! Please open an issue first to discuss what you'd like to change.
+
+[GitHub Repository](https://github.com/oblongmedulla/homebridge-pawport)
+
+---
+
+## License
+
+MIT © [oblongmedulla](https://github.com/oblongmedulla)

package/config.schema.json

@@ -0,0 +1,63 @@
+{
+  "pluginAlias": "PawportPlatform",
+  "pluginType": "platform",
+  "singular": false,
+  "headerDisplay": "Control your Pawport smart pet door(s) from Apple Home. [Get your auth token and door ID →](https://github.com/oblongmedulla/homebridge-pawport#finding-your-credentials)",
+  "footerDisplay": "For help, visit the [GitHub repo](https://github.com/oblongmedulla/homebridge-pawport).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "Pawport",
+        "required": true
+      },
+      "doors": {
+        "title": "Doors",
+        "type": "array",
+        "required": true,
+        "minItems": 1,
+        "items": {
+          "title": "Door",
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Door Name",
+              "type": "string",
+              "placeholder": "e.g. Back Door, Dog Door",
+              "required": true
+            },
+            "authToken": {
+              "title": "Auth Token (x-auth-token)",
+              "type": "string",
+              "placeholder": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+              "required": true,
+              "description": "Your Pawport account auth token. See README for how to find this."
+            },
+            "doorID": {
+              "title": "Door ID",
+              "type": "string",
+              "placeholder": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+              "required": true,
+              "description": "The UUID of your Pawport door. See README for how to find this."
+            }
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    {
+      "key": "doors",
+      "type": "array",
+      "title": "Doors",
+      "buttonText": "Add Door",
+      "items": [
+        "doors[].name",
+        "doors[].authToken",
+        "doors[].doorID"
+      ]
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const PLUGIN_NAME = 'homebridge-pawport';
+const PLATFORM_NAME = 'PawportPlatform';
+const GRAPHQL_URL = 'https://api.app.pawport.com/graphql';
+
+const SEND_DOOR_COMMAND_MUTATION = `
+  mutation sendDoorCommand($command: String!, $doorID: String!, $arguments: json) {
+    sendDoorCommand(command: $command, doorID: $doorID, arguments: $arguments)
+  }
+`;
+
+module.exports = (api) => {
+  api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, PawportPlatform);
+};
+
+// ─── Platform ────────────────────────────────────────────────────────────────
+
+class PawportPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config;
+    this.api = api;
+    this.accessories = [];
+
+    if (!config || !config.doors || config.doors.length === 0) {
+      this.log.warn('No doors configured. Add at least one door in your Homebridge config.');
+      return;
+    }
+
+    this.api.on('didFinishLaunching', () => {
+      this.syncAccessories();
+    });
+  }
+
+  syncAccessories() {
+    const configuredIDs = new Set(this.config.doors.map(d => d.doorID));
+
+    // Remove accessories that are no longer in config
+    this.accessories = this.accessories.filter(acc => {
+      if (!configuredIDs.has(acc.context.doorID)) {
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [acc]);
+        return false;
+      }
+      return true;
+    });
+
+    // Add or restore accessories for each configured door
+    for (const doorConfig of this.config.doors) {
+      if (!doorConfig.doorID || !doorConfig.authToken) {
+        this.log.warn(`Door "${doorConfig.name}" is missing doorID or authToken — skipping.`);
+        continue;
+      }
+
+      const uuid = this.api.hap.uuid.generate(doorConfig.doorID);
+      const existing = this.accessories.find(a => a.UUID === uuid);
+
+      if (existing) {
+        this.log.info(`Restoring door: ${doorConfig.name}`);
+        new PawportAccessory(this.log, existing, this.api, doorConfig);
+      } else {
+        this.log.info(`Adding door: ${doorConfig.name}`);
+        const accessory = new this.api.platformAccessory(doorConfig.name, uuid);
+        accessory.context.doorID = doorConfig.doorID;
+        new PawportAccessory(this.log, accessory, this.api, doorConfig);
+        this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+      }
+    }
+  }
+
+  configureAccessory(accessory) {
+    this.accessories.push(accessory);
+  }
+}
+
+// ─── Accessory ───────────────────────────────────────────────────────────────
+
+class PawportAccessory {
+  constructor(log, accessory, api, config) {
+    this.log = log;
+    this.accessory = accessory;
+    this.api = api;
+    this.config = config;
+
+    this.authToken = config.authToken;
+    this.doorID = config.doorID;
+
+    // Current state tracking
+    this.currentState = api.hap.Characteristic.LockCurrentState.SECURED;
+    this.targetState = api.hap.Characteristic.LockTargetState.SECURED;
+
+    // Set accessory info
+    this.accessory
+      .getService(api.hap.Service.AccessoryInformation)
+      .setCharacteristic(api.hap.Characteristic.Manufacturer, 'Pawport')
+      .setCharacteristic(api.hap.Characteristic.Model, 'Smart Pet Door')
+      .setCharacteristic(api.hap.Characteristic.SerialNumber, this.doorID);
+
+    // Set up lock service
+    this.lockService =
+      this.accessory.getService(api.hap.Service.LockMechanism) ||
+      this.accessory.addService(api.hap.Service.LockMechanism, config.name);
+
+    this.lockService
+      .getCharacteristic(api.hap.Characteristic.LockCurrentState)
+      .onGet(() => this.currentState);
+
+    this.lockService
+      .getCharacteristic(api.hap.Characteristic.LockTargetState)
+      .onGet(() => this.targetState)
+      .onSet(async (value) => {
+        this.targetState = value;
+        const shouldLock = value === api.hap.Characteristic.LockTargetState.SECURED;
+        this.log.info(`${config.name}: ${shouldLock ? 'Locking' : 'Unlocking'}...`);
+
+        try {
+          const success = await this.sendDoorCommand('door_lock', { locked: shouldLock });
+
+          if (success) {
+            this.currentState = shouldLock
+              ? api.hap.Characteristic.LockCurrentState.SECURED
+              : api.hap.Characteristic.LockCurrentState.UNSECURED;
+
+            this.lockService
+              .getCharacteristic(api.hap.Characteristic.LockCurrentState)
+              .updateValue(this.currentState);
+
+            this.log.info(`${config.name}: ${shouldLock ? 'Locked ✓' : 'Unlocked ✓'}`);
+          } else {
+            throw new Error('API returned false');
+          }
+        } catch (err) {
+          this.log.error(`${config.name}: Command failed — ${err.message}`);
+          // Revert target state to match current on failure
+          this.targetState = shouldLock
+            ? api.hap.Characteristic.LockTargetState.UNSECURED
+            : api.hap.Characteristic.LockTargetState.SECURED;
+          this.lockService
+            .getCharacteristic(api.hap.Characteristic.LockTargetState)
+            .updateValue(this.targetState);
+          throw new api.hap.HapStatusError(api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+        }
+      });
+  }
+
+  async sendDoorCommand(command, args = {}) {
+    const body = {
+      operationName: 'sendDoorCommand',
+      variables: {
+        doorID: this.doorID,
+        command,
+        arguments: args,
+      },
+      query: SEND_DOOR_COMMAND_MUTATION,
+    };
+
+    const response = await fetch(GRAPHQL_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-auth-token': this.authToken,
+        'Accept': '*/*',
+        'User-Agent': 'homebridge-pawport',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+
+    if (data.errors) {
+      throw new Error(data.errors.map(e => e.message).join(', '));
+    }
+
+    return data?.data?.sendDoorCommand === true;
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+"name": "@oblongmedulla/homebridge-pawport",
+  "version": "1.0.0",
+  "description": "Homebridge plugin for the Pawport smart pet door",
+  "license": "MIT",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin",
+    "pawport",
+    "pet door",
+    "smart lock",
+    "homebridge"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": ">=1.3.0"
+  },
+  "author": "oblongmedulla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oblongmedulla/homebridge-pawport.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oblongmedulla/homebridge-pawport/issues"
+  },
+  "homepage": "https://github.com/oblongmedulla/homebridge-pawport#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "homebridge": "^1.8.0"
+  }
+}