> For the complete documentation index, see [llms.txt](https://docs.dephy.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dephy.io/dephy-stream/for-developers.md).

# For Developers

#### 👌 **1. Register a Topic (Create Stream)**

Frontend: 👉 <https://stream.dephy.dev/>

1. Open the sidebar → **Create Stream** tab.

   <figure><img src="/files/s4W2VoL0xecu5UuzmIyr" alt=""><figcaption></figcaption></figure>
2. Fill in:
   * **Name** — Topic name
   * **Description** — optional
   * **Admin** — nostr pubkey of the topic administrator
   * **Publish Mode** — *Public* or *Private*
   * **Access Mode** — *Public*, *Private*, or *Subscription*
3. Click **Create Stream**.

**Mode Notes**

| Mode Type        | Option           | Description                                                                                            |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| **Publish Mode** | **Public**       | Any nostr pubkey can publish events.                                                                   |
|                  | **Private**      | Only nostr pubkeys explicitly granted publish rights by Admin can publish.                             |
| **Access Mode**  | **Public**       | Everyone can view/subscribe.                                                                           |
|                  | **Private**      | Admin must grant access to each nostr pubkey.                                                          |
|                  | **Subscription** | Access requires payment (token + monthly fee). After payment and an auth epoch, access becomes active. |

> ⚙️ **Auth Epoch Delay:** After granting permissions or processing payment, expect a short delay (\~5 min by default) before the auth service updates. You can adjust this in your deployed `dephy-mn-auth` configuration.

***

#### 👌 **2. How to Get Access to a Topic**

1. Open the sidebar → **Streams** tab.

   <figure><img src="/files/9mlJS5pdS9LUgZqHrqCJ" alt=""><figcaption></figcaption></figure>
2. Open **qingping\_air\_monitor** stream.

   <figure><img src="/files/MgyyIPPgwJvITgAk6Sgk" alt=""><figcaption></figcaption></figure>

| Topic Type       | Access Instructions                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| **Public**       | No setup needed — open the Stream page.                                                                  |
| **Private**      | Ask the Admin to `grant access` to your nostr pubkey. Wait one auth epoch, then authenticate and access. |
| **Subscription** | Click **Subscribe** → complete payment → wait for auth epoch → refresh Stream page.                      |

> Admins can manage permissions (`grant/revoke publish` / `grant/revoke access`) from the **Streams** tab when signed in.

***

#### 👌 **3. How to Subscribe to a Topic**

1. Open the Topic page.
2. If it’s a **Subscription** type, click **Subscribe** and complete payment.

   <figure><img src="/files/qlsRrdkTeFtXzouai4QN" alt=""><figcaption></figcaption></figure>
3. Wait for the auth epoch (\~5 min).&#x20;
4. Refresh to view stream events.

   <figure><img src="/files/UcJuOsk1MHJiynCgSC1s" alt=""><figcaption></figcaption></figure>

***

#### 👌 **4. Add a New Device Type to `hass2nostr`**

Device modules live under: `src/device-types/*.ts`

Each must export:

| Export                            | Description                                                |
| --------------------------------- | ---------------------------------------------------------- |
| `entityPrefixes: string[]`        | List of entity\_id prefixes to match in Home Assistant.    |
| `allowedEntitySuffixes: string[]` | Limits which entity\_ids under those prefixes are used.    |
| `allowedAttributes: string[]`     | Keys to keep in the truncated attributes.                  |
| `truncateAttributes(attributes)`  | Function to return only permitted attributes.              |
| `processState(hassState[])`       | Processes/truncates states. Usually wraps `truncateState`. |
| `simulateHassState(device)`       | Generates fake Home Assistant states for simulation.       |

**Implementation Notes**

* See examples: `qingping_air_monitor.ts`, `chunmi_tsa1.ts`, `zhimi_mp4a.ts`
* The CLI imports these modules (`src/cli/bridge.ts`, `src/cli/simulate.ts`) and filters Home Assistant states accordingly.
* Keep filename = deviceType name (e.g. `-w qingping_air_monitor` loads `src/device-types/qingping_air_monitor.ts`).

**Minimal Checklist**

1. Create `src/device-types/<your_device>.ts`
2. Export required constants/functions
3. Implement `truncateAttributes()`
4. Add `processState()` and `simulateHassState()`
5. Test with:

```bash
deno task run simulate -r wss://canary-relay.dephy.dev -w <your_device>
```

**Example**

```ts
export const entityPrefixes = ["sensor.my_vendor_thing_"];
export const allowedEntitySuffixes = ["temperature", "humidity"];
export const allowedAttributes = [
  "state_class",
  "unit_of_measurement",
  "device_class",
];

export function truncateAttributes(attrs) {
  const allowed = {};
  for (const key of allowedAttributes) {
    if (key in attrs) allowed[key] = attrs[key];
  }
  return allowed;
}

export function processState(states) {
  return states.map((s) => truncateState(s, truncateAttributes));
}

export function simulateHassState(device) {
  // Return mock HassState[] for testing
}
```

***