@hasna/contacts 0.6.22 → 0.6.27

package/README.md

@@ -17,6 +17,33 @@ npm install -g @hasna/contacts
 contacts --help
 ```
 
+## Audiences, consent, and suppression
+
+Audience segments implement the `hasna.audience.v1` contract (distribution
+apps plan): predicate definitions over contact tags, attributes (columns or
+custom fields), and group membership, resolved to per-channel recipient lists
+that honor consent and suppression.
+
+```bash
+contacts audience create beta-testers \
+  --name "Beta testers" \
+  --predicates '[{"kind":"tag","value":"beta"}]' \
+  --policy opt_in
+contacts audience list
+contacts audience show beta-testers          # hasna.audience.v1 document
+contacts audience resolve beta-testers --channel email    # email|telegram|sms
+contacts consent set CONTACT_ID --channel email --status opt_in
+contacts suppression add someone@example.com --channel email --reason unsubscribe
+contacts suppression sync --dry-run          # push unsubscribes to mailery
+```
+
+Resolution always excludes archived and `do_not_contact` contacts and
+suppressed addresses; the audience `--policy` (`opt_in`, `opt_out`,
+`transactional`, `none`) controls how per-channel consent is applied.
+`contacts suppression sync` pushes unsynced email suppressions to mailery via
+`@hasna/mailery` when it is installed; any other backend can implement the
+`SuppressionSyncAdapter` interface exported from the package.
+
 ## MCP Server
 
 ```bash
@@ -44,6 +71,18 @@ The REST server (`contacts-serve`) also exposes `/health` and `/mcp` when runnin
 contacts-serve
 ```
 
+`contacts-serve` binds to `127.0.0.1` by default. Use `--host <host>` or
+`CONTACTS_HOST=<host>` only when intentionally exposing it beyond loopback.
+Shared binds still fail closed unless a valid contacts token is configured and
+sent with the request. The unauthenticated local development fallback is disabled
+by default and only activates when all of the following are true:
+
+- no contacts API token environment variable is configured
+- `CONTACTS_ALLOW_UNAUTHENTICATED_LOOPBACK=1`
+- the server is explicitly bound to a loopback host
+
+The fallback does not trust the HTTP `Host` header.
+
 ## Storage
 
 Contacts owns its local SQLite storage directly. It does not depend on shared
@@ -52,14 +91,51 @@ cloud runtime commands or MCP tools.
 ```bash
 contacts storage status
 contacts storage status --json
-contacts cloud status --json
+contacts storage push --tables contacts,companies
+contacts storage pull --tables contacts,companies
+contacts storage sync
+```
+
+Optional cross-machine sync uses contacts-owned PostgreSQL storage. Set one of:
+
+```bash
+export HASNA_CONTACTS_POSTGRES_URL="postgres://..."
+# or OPEN_CONTACTS_POSTGRES_URL / CONTACTS_POSTGRES_URL
 ```
 
-`contacts cloud status` remains as a compatibility alias that reports local
-storage and remote-sync availability. `contacts cloud push` and
-`contacts cloud pull` return a clear unsupported message until repo-native
-remote sync is configured inside this package. `contacts cloud feedback` saves
-feedback locally in the contacts database.
+Remote PostgreSQL connections require verified TLS for non-local hosts. Local
+PostgreSQL development URLs can disable TLS explicitly.
+
+By default, remote sync covers contacts, companies, tags, and the other
+non-sensitive relationship tables. `webhooks`, `contact_documents`, and
+`contact_health` are excluded until explicitly requested with `--tables` and
+`HASNA_CONTACTS_ALLOW_SENSITIVE_SYNC=1`. Sync inserts or updates rows with
+timestamp conflict protection. Deletes for `contacts`, `companies`, and `tags`
+write `_contacts_tombstones`; push/pull sync carries those tombstones and pull
+applies them unless the local row has a newer `updated_at`.
+
+Shared REST/dashboard deployments must set one of
+`HASNA_CONTACTS_API_TOKENS`, `OPEN_CONTACTS_API_TOKENS`, or
+`CONTACTS_API_TOKENS`. Values are comma-separated `token=scope scope` records.
+Supported scopes include `contacts:read`, `contacts:write`,
+`contacts:import`, `contacts:export`, `contacts:export:full`,
+`documents:read`, `images:read`, `images:write`, `companies:*`, `tags:*`,
+`stats:read`, `dashboard:read`, and `mcp:access`. Loopback-only development
+without configured tokens remains allowed; shared hosts fail closed.
+
+Server exports are redacted by default: email addresses, phone numbers,
+addresses, notes, birthdays, social profiles, and custom fields are withheld.
+Full exports require both `contacts:export` and `contacts:export:full`. Export,
+import, document file read, image mutation, contact mutation, company mutation,
+and tag mutation routes write audit entries. Document attachments are served
+only from the managed contacts documents directory and use private `no-store`
+cache headers.
+
+`contacts cloud status`, `contacts cloud push`, `contacts cloud pull`, and
+`contacts cloud sync` remain compatibility aliases for the contacts-owned
+storage commands. They do not load or depend on the deprecated shared cloud
+runtime. `contacts cloud feedback` saves feedback locally in the contacts
+database.
 
 ## Data Directory
 

package/dist/cli/commands/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAg7B/D"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAo5B/D"}

package/dist/cli/commands/audience.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Audience / consent / suppression commands (distribution apps plan).
+ *
+ *   contacts audience create <slug> --name <name> --predicates <json> [--match all|any] [--policy <policy>]
+ *   contacts audience list
+ *   contacts audience show <id>
+ *   contacts audience delete <id>
+ *   contacts audience resolve <id> --channel email|telegram|sms [--json]
+ *   contacts consent set <contactId> --channel <channel> --status opt_in|opt_out|unknown [--source <source>]
+ *   contacts consent show <contactId>
+ *   contacts suppression add <address> --channel <channel> [--contact <id>] [--reason <reason>]
+ *   contacts suppression remove <address> --channel <channel>
+ *   contacts suppression list [--channel <channel>] [--unsynced]
+ *   contacts suppression sync [--dry-run]
+ */
+import type { Command } from "commander";
+export declare function registerAudienceCommands(program: Command): void;
+//# sourceMappingURL=audience.d.ts.map

package/dist/cli/commands/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/audience.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6P/D"}

package/dist/cli/commands/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6CzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAq3B3D"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAk5B3D"}

package/dist/cli/commands/crm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgDzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAs7B1D"}
+{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAy6B1D"}