typefully-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/.github/workflows/ci.yml

@@ -29,3 +29,10 @@ jobs:
 
       - name: Test
         run: python -m pytest tests/ -v
+
+  collector:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - name: Test collector (mocked storage, no network)
+        run: node --test collector/worker.test.mjs

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0 (unreleased)
+
+- Add minimal default-on usage telemetry for interactive text commands only, after a visible disclosure. The first notice invocation sends nothing.
+- Disable with `TYPEFULLY_TELEMETRY=0` or `typefully config set telemetry_enabled false`. CI, noninteractive, JSON and quiet runs are excluded.
+- Send only CLI version and command category to a maintainer-owned collector; store daily aggregate counts, not unique-user IDs or content. Network infrastructure still sees source IP.
+- Add strict collector validation, privacy documentation and mocked telemetry tests. See `docs/telemetry.md` for retention and limits.
+
 ## 0.3.0 (2026-10-29)
 
 - Add schema-backed `draft-payload` request-file input with offline validation, per-post fields and null/false clearing; keep `--json` as output-only.

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: typefully-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI for the Typefully API -- manage drafts, threads, and publishing from the terminal
 Project-URL: Homepage, https://github.com/dheeraj-shah/typefully-cli
 Project-URL: Repository, https://github.com/dheeraj-shah/typefully-cli
@@ -331,6 +331,14 @@ account = "MyBrand"
 output_format = "text"   # or "json" for agent/script use
 ```
 
+## Usage telemetry
+
+This unreleased branch counts CLI version and command category only through a
+maintainer-owned collector, after a visible notice. The first notice invocation
+sends nothing. Published 0.3.0 installations are unchanged until a new release.
+Disable with `TYPEFULLY_TELEMETRY=0` or
+`typefully config set telemetry_enabled false`. See [privacy and activation details](docs/telemetry.md).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/README.md

@@ -296,6 +296,14 @@ account = "MyBrand"
 output_format = "text"   # or "json" for agent/script use
 ```
 
+## Usage telemetry
+
+This unreleased branch counts CLI version and command category only through a
+maintainer-owned collector, after a visible notice. The first notice invocation
+sends nothing. Published 0.3.0 installations are unchanged until a new release.
+Disable with `TYPEFULLY_TELEMETRY=0` or
+`typefully config set telemetry_enabled false`. See [privacy and activation details](docs/telemetry.md).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

typefully_cli-0.4.0/collector/DEPLOYMENT.md

@@ -0,0 +1,54 @@
+# Deployment verification — 2026-10-29
+
+Owner approved dedicated personal Cloudflare Worker + D1 creation on the confirmed
+Workers/D1 Free plan; no plan change, credentials, or security grants were made.
+
+- Endpoint: `https://typefully-cli-telemetry.dheeraj-personal-site.workers.dev/v1/count`
+- Worker: `typefully-cli-telemetry`
+- Account: `22980d1f74f2694e0642ea3cf9f384d9` (Dheeraj Shah)
+- D1: `typefully-cli-telemetry`, ID `1c795c09-fb39-41bf-bf9d-a4f7deae6c9c`
+- Worker version: `e251b178-c17f-44d1-99e5-ca1006ad1067`
+- D1 read replication: disabled
+
+Uploaded `worker.mjs` with only its default fetch export. The API upload response
+confirmed `observability.enabled=false`, log/invocation-log/trace enabled flags
+false, both log/trace persistence flags false, `logpush=false`, and empty tail
+consumers. Subsequent settings readback confirmed the dedicated D1 binding,
+`logpush=false` and empty tail consumers; disabled observability was omitted from
+that read response. Account Logpush jobs list was empty. The workers.dev route was
+read back enabled with preview URLs disabled.
+
+Checks against the deployed endpoint used no real usage:
+
+- GET `/v1/count` returned 405 with an empty body.
+- POST of the rejected synthetic dimensions `synthetic-test` / `synthetic-test`
+  returned 400 with an empty body.
+- D1 schema readback showed only `day`, `version`, `category`, `count`.
+- D1 count after both checks: zero rows. No production-dimension count was sent.
+- Local Node tests: 7 passed. SQLite schema/upsert checked locally.
+
+This verifies the rejection path and deployed configuration, not a production
+accepted-event end-to-end write. Accepted payload/database behavior is tested
+locally with a mock D1 binding. Cloudflare infrastructure still receives IP and
+transport metadata; application configuration and account Logpush checks do not
+verify all provider-internal security retention. No claim of full anonymity.
+
+The example Wrangler configuration remains intentionally inactive. An operator
+must copy it and explicitly supply the above binding/approved route before future
+deployment. Do not upgrade the Free plan automatically; quota exhaustion should
+leave telemetry best-effort, not change CLI behavior or authorize charges.
+
+## Prepared 0.4.0 candidate update — 12:20 UTC
+
+The existing collector was redeployed with only the reviewed version allowlist
+expanded from `0.3.0` to `0.3.0` and `0.4.0`; the CLI candidate is not published.
+Downloaded deployed source confirmed both exact versions. Local mock tests accept
+both and reject `0.4.0-rc.1`, `0.4.1`, and `0.5.0`.
+
+Upload again confirmed all observability/logging/tracing and persistence flags
+false, Logpush false, and no tail consumers. Settings readback confirmed the same
+D1 binding and no Logpush/tails; account Logpush jobs remain empty. Route remains
+enabled and previews disabled. A rejected synthetic POST returned 400 with zero
+response bytes; a subsequent D1 count confirmed zero rows. No accepted production
+payload was sent. No resources, paid plan
+changes, credentials, or grants were added by this update.

typefully_cli-0.4.0/collector/README.md

@@ -0,0 +1,70 @@
+# Minimal usage collector
+
+Owned Cloudflare Worker + dedicated D1 database. The owner approved the dedicated
+Free-plan deployment on 2026-10-29. See [deployment verification](DEPLOYMENT.md) for
+the exact recipient and checks. No credentials or deployment automation are bundled.
+CLI publication/release remains a separate approval.
+
+## Data contract
+
+`POST /v1/count`, `Content-Type: application/json`, at most 256 UTF-8 bytes:
+
+```json
+{"version":"0.3.0","category":"drafts"}
+```
+
+Only reviewed release versions are accepted (`VERSIONS`: `0.3.0` and the prepared
+`0.4.0` candidate); add a version explicitly
+when releasing. Categories: `account`, `drafts`, `publishing`, `media`, `tags`,
+`analytics`, `comments`, `queue`. Other keys/values and URLs with query strings are
+rejected. The application ignores all request headers except content type.
+
+The only database columns are UTC day (generated by the server), release version,
+category, and aggregate invocation count. An atomic upsert increments that day's
+count; there are no per-invocation rows, identifiers, fingerprints, IP addresses,
+user agents, content, tokens, arguments, or errors stored by the application.
+Counts measure activity, **not unique people**, and can be inflated by anyone
+sending valid requests: this is deliberately an unauthenticated, non-identifying
+counter, not trustworthy billing or security data.
+
+On each accepted request the same D1 transaction removes aggregate rows older
+than 90 days. If traffic stops, old aggregate rows remain until another accepted
+request or an operator deletes them. D1 backups may temporarily retain deleted
+aggregate rows. No application request logs, traces, or Logpush are enabled in the
+template; do not enable tail consumers or add request logging.
+
+Cloudflare necessarily receives source IP and other transport metadata. This code
+cannot promise that Cloudflare's independent infrastructure/security processing
+retains none of it. Review the service's current policies and account settings
+before enabling collection; do not describe it as fully anonymous.
+
+## Local verification (no HTTP traffic)
+
+```sh
+node --test collector/worker.test.mjs
+```
+
+Tests use in-memory Requests and a fake D1 binding; they never call a live endpoint.
+
+## Deployment approval checklist
+
+1. Approve the exact owner/account, endpoint and disclosed recipient. Verify the
+   account's current Workers/D1 billing plan, quotas and limits; do not assume zero
+   cost from the word "free". Do not upgrade a plan or grant new credentials.
+2. Approve creation of a dedicated Worker and dedicated D1 database. Do not reuse a
+   newsletter/customer database or Worker with request logging enabled.
+3. Copy `wrangler.example.jsonc` to a private deployment configuration, add the
+   approved D1 binding named `COUNTS`, and apply `schema.sql` to that database.
+4. Verify observability logs/traces, invocation logs, Logpush and tail consumers are
+   disabled in effective deployed settings, including any account-level exports.
+   Review platform retention separately. Enable only the approved HTTPS route.
+5. Update the CLI compiled endpoint and its disclosure together after approval.
+   Run mocked tests and review the diff. Publishing/releasing remains a separate
+   approval; deployment is not permission to release the CLI.
+6. Do not perform a real telemetry smoke test without approval for that payload and
+   recipient. A health check must not record an event.
+
+Current API references used when preparing this proposal:
+[Workers best practices](https://developers.cloudflare.com/workers/best-practices/workers-best-practices/),
+[D1 prepared statements](https://developers.cloudflare.com/d1/worker-api/prepared-statements/),
+[Wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/).

typefully_cli-0.4.0/collector/schema.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS daily_counts (
+    day TEXT NOT NULL,
+    version TEXT NOT NULL,
+    category TEXT NOT NULL,
+    count INTEGER NOT NULL CHECK (count > 0),
+    PRIMARY KEY (day, version, category)
+) WITHOUT ROWID;

typefully_cli-0.4.0/collector/worker.mjs

@@ -0,0 +1,72 @@
+// This collector deliberately never records request headers, IPs, or event-level data.
+const VERSIONS = new Set(['0.3.0', '0.4.0']);
+const CATEGORIES = new Set(['account', 'drafts', 'publishing', 'media', 'tags', 'analytics', 'comments', 'queue']);
+const MAX_BYTES = 256;
+
+async function readPayload(request) {
+  if (!request.body) throw new Error('invalid');
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_BYTES) {
+        await reader.cancel();
+        throw new Error('invalid');
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  if (!data || Array.isArray(data) || typeof data !== 'object'
+      || Object.keys(data).sort().join(',') !== 'category,version'
+      || !VERSIONS.has(data.version) || !CATEGORIES.has(data.category)) {
+    throw new Error('invalid');
+  }
+  return data;
+}
+
+const response = (status) => new Response(null, {
+  status, headers: { 'Cache-Control': 'no-store' },
+});
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (url.pathname !== '/v1/count' || url.search) return response(404);
+    if (request.method !== 'POST') return response(405);
+    if (request.headers.get('content-type') !== 'application/json') return response(415);
+    let data;
+    try {
+      data = await readPayload(request);
+    } catch {
+      return response(400);
+    }
+    try {
+      // Only UTC day, approved release version/category, and an aggregate count reach D1.
+      const day = new Date().toISOString().slice(0, 10);
+      const cutoff = new Date(Date.now() - 90 * 86400000).toISOString().slice(0, 10);
+      await env.COUNTS.batch([
+        env.COUNTS.prepare('DELETE FROM daily_counts WHERE day < ?').bind(cutoff),
+        env.COUNTS.prepare(`INSERT INTO daily_counts (day, version, category, count)
+          VALUES (?, ?, ?, 1)
+          ON CONFLICT(day, version, category) DO UPDATE SET count = count + 1`)
+          .bind(day, data.version, data.category),
+      ]);
+      return response(204);
+    } catch {
+      return response(503);
+    }
+  },
+};

typefully_cli-0.4.0/collector/worker.test.mjs

@@ -0,0 +1,123 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import worker from './worker.mjs';
+const CATEGORIES = ['account', 'drafts', 'publishing', 'media', 'tags', 'analytics', 'comments', 'queue'];
+
+function database(fail = false) {
+  const batches = [];
+  return {
+    batches,
+    prepare(sql) { return { bind: (...values) => ({ sql, values }) }; },
+    async batch(statements) {
+      if (fail) throw new Error('private backend details');
+      batches.push(statements);
+    },
+  };
+}
+function request(body = { version: '0.3.0', category: 'drafts' }, options = {}) {
+  return new Request('https://collector.invalid/v1/count', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: typeof body === 'string' ? body : JSON.stringify(body), ...options,
+  });
+}
+
+test('every category stores only daily aggregate dimensions; never headers', async () => {
+  for (const category of CATEGORIES) {
+    const db = database();
+    const req = request({ version: '0.3.0', category });
+    req.headers.set('CF-Connecting-IP', '192.0.2.1');
+    req.headers.set('User-Agent', 'private-machine-name');
+    req.headers.set('Authorization', 'Bearer secret');
+    const res = await worker.fetch(req, { COUNTS: db });
+    assert.equal(res.status, 204);
+    assert.equal(res.headers.get('Cache-Control'), 'no-store');
+    assert.equal(db.batches.length, 1);
+    const [cleanup, increment] = db.batches[0];
+    assert.match(cleanup.sql, /DELETE FROM daily_counts/);
+    assert.match(cleanup.values[0], /^\d{4}-\d{2}-\d{2}$/);
+    assert.match(increment.sql, /ON CONFLICT.*DO UPDATE SET count = count \+ 1/);
+    assert.deepEqual(increment.values, [new Date().toISOString().slice(0, 10), '0.3.0', category]);
+    assert.doesNotMatch(JSON.stringify(db.batches), /secret|private-machine-name|192\.0/);
+  }
+});
+
+test('accepts both reviewed release versions without broadening the allowlist', async () => {
+  for (const version of ['0.3.0', '0.4.0']) {
+    const db = database();
+    assert.equal((await worker.fetch(request({ version, category: 'drafts' }), { COUNTS: db })).status, 204);
+    assert.equal(db.batches[0][1].values[1], version);
+  }
+  for (const version of ['0.4.0-rc.1', '0.4.1', '0.5.0']) {
+    const db = database();
+    assert.equal((await worker.fetch(request({ version, category: 'drafts' }), { COUNTS: db })).status, 400);
+    assert.deepEqual(db.batches, []);
+  }
+});
+
+test('rejects malformed, unapproved, and extra fields before storage', async () => {
+  for (const body of [
+    'not json', 'null', '[]', '"text"', '{}',
+    { version: '0.3.0', category: 'drafts', content: 'secret' },
+    { version: '0.3.0', category: 'unknown' },
+    { version: 'my-private-build', category: 'drafts' },
+    { version: '99.99.99', category: 'drafts' },
+    { version: 3, category: 'drafts' },
+    { version: '0.3.0', category: ['drafts'] },
+    ' '.repeat(257),
+  ]) {
+    const db = database();
+    const res = await worker.fetch(request(body), { COUNTS: db });
+    assert.equal(res.status, 400, JSON.stringify(body));
+    assert.deepEqual(db.batches, []);
+  }
+});
+
+test('bounded streamed body ignores forged Content-Length', async () => {
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(' '.repeat(200)));
+      controller.enqueue(new TextEncoder().encode(' '.repeat(200)));
+      controller.close();
+    },
+  });
+  const db = database();
+  const req = request('', { body: stream, duplex: 'half', headers: {
+    'Content-Type': 'application/json', 'Content-Length': '1',
+  } });
+  assert.equal((await worker.fetch(req, { COUNTS: db })).status, 400);
+  assert.deepEqual(db.batches, []);
+});
+
+test('rejects invalid UTF-8, route, query, method and content type', async () => {
+  const db = database();
+  for (const [req, status] of [
+    [request('', { body: new Uint8Array([0xff]) }), 400],
+    [new Request('https://collector.invalid/'), 404],
+    [new Request('https://collector.invalid/v1/count?secret=1'), 404],
+    [new Request('https://collector.invalid/v1/count'), 405],
+    [request('{}', { headers: { 'Content-Type': 'text/plain' } }), 415],
+  ]) assert.equal((await worker.fetch(req, { COUNTS: db })).status, status);
+  assert.deepEqual(db.batches, []);
+});
+
+test('storage errors do not expose backend details or fail open', async () => {
+  const res = await worker.fetch(request(), { COUNTS: database(true) });
+  assert.equal(res.status, 503);
+  assert.equal(await res.text(), '');
+});
+
+test('deployment template keeps public routes and application logging disabled', async () => {
+  const { readFile } = await import('node:fs/promises');
+  const template = await readFile(new URL('./wrangler.example.jsonc', import.meta.url), 'utf8');
+  const cfg = JSON.parse(template.replace(/\/\/.*$/gm, ''));
+  assert.equal(cfg.workers_dev, false);
+  assert.equal(cfg.preview_urls, false);
+  assert.equal(cfg.logpush, false);
+  assert.equal(cfg.observability.enabled, false);
+  assert.equal(cfg.observability.logs.enabled, false);
+  assert.equal(cfg.observability.logs.invocation_logs, false);
+  assert.equal(cfg.observability.traces.enabled, false);
+  assert.equal(cfg.routes, undefined);
+  assert.equal(cfg.account_id, undefined);
+  assert.equal(cfg.d1_databases, undefined);
+});

typefully_cli-0.4.0/collector/wrangler.example.jsonc

@@ -0,0 +1,15 @@
+{
+  "name": "typefully-cli-telemetry",
+  "main": "worker.mjs",
+  "compatibility_date": "2026-10-29",
+  "workers_dev": false,
+  "preview_urls": false,
+  "logpush": false,
+  "observability": {
+    "enabled": false,
+    "logs": { "enabled": false, "invocation_logs": false },
+    "traces": { "enabled": false }
+  }
+  // After explicit deployment approval, add a dedicated D1 binding named COUNTS,
+  // with the approved database_name/database_id, and enable the approved route.
+}

typefully_cli-0.4.0/docs/release-0.4.0.md

@@ -0,0 +1,37 @@
+# 0.4.0 release candidate
+
+Prepared, not published. A minor version reflects the new default-on telemetry
+feature. On 2026-10-29 PyPI reported latest version 0.3.0 and no 0.4.0; the remote
+Git tags had no v0.4.0. Recheck immediately before publication.
+
+## Release contract
+
+- Package metadata and runtime version: 0.4.0.
+- Collector explicitly accepts 0.4.0 alongside the previous reviewed 0.3.0.
+- First eligible interactive text invocation displays disclosure and sends nothing.
+- Later eligible invocations send only version/category. Opt out with
+  `TYPEFULLY_TELEMETRY=0` or `typefully config set telemetry_enabled false`.
+- CI, noninteractive, JSON and quiet invocations do not send.
+- Skill and privacy documentation describe these controls and infrastructure IP visibility.
+
+## Final checks
+
+Run the complete Python suite, CI Ruff selection, Node collector tests and
+`git diff --check`. Build both sdist and wheel with `python -m build` and validate
+metadata using `python -m twine check dist/typefully_cli-0.4.0*`. Install the wheel
+in a clean environment and check version, help, offline payload validation and
+opt-out persistence with networking blocked. Verify artifact versions, schema and
+telemetry source; ensure the source distribution includes skill/privacy documents.
+All telemetry tests use mocks; do not send real usage as a release check.
+
+## Publication remains gated
+
+Do not merge, create/push `v0.4.0`, publish to PyPI, create a GitHub release, or change
+Homebrew until the owner approves those exact destinations. Pushing a `v*` tag
+triggers the existing trusted PyPI publishing workflow. A PR push does not.
+Homebrew is maintained separately; coordinate after the release is available,
+without touching its current 0.3.0 work.
+
+Suggested approval question: **May I merge PR #16 and publish typefully-cli 0.4.0
+by pushing tag v0.4.0 (which triggers PyPI), then create the matching GitHub release?
+Homebrew updates would be handled separately.**

typefully_cli-0.4.0/docs/telemetry.md

@@ -0,0 +1,65 @@
+# Usage telemetry
+
+## Current status
+
+The maintainer-owned collector is deployed at
+`https://typefully-cli-telemetry.dheeraj-personal-site.workers.dev/v1/count`.
+This unreleased branch is configured to use it, subject to the notice and opt-out
+rules below. Existing published 0.3.0 installations are unchanged. A package
+release still requires separate approval. There is no third-party analytics SDK.
+See [deployment verification](../collector/DEPLOYMENT.md).
+
+## What an activated build measures
+
+A request contains only the released CLI version and an allowlisted command
+category: account, drafts, publishing, media, tags, analytics, comments, or queue.
+It does not contain command arguments, post text, API keys, account information,
+errors, hostnames, installation IDs, or device identifiers. It measures command
+activity, **not unique users**, installations, or successful API operations.
+
+The collector increments a daily aggregate count for version/category. It does
+not store individual events or application-level IP/user-agent logs. Aggregate rows
+older than 90 days are removed on the next accepted request; if traffic stops,
+they remain until another request or operator cleanup. Backups may retain deleted
+aggregates temporarily. Network and
+hosting infrastructure necessarily receive source IPs and connection metadata;
+this is not a promise of full anonymity or zero infrastructure retention.
+
+## Notice and opt-out
+
+Before any sending can begin, an interactive invocation displays a notice naming
+the collector and opt-out controls. That invocation sends nothing. Only a later
+eligible invocation can send. A local marker records that notice for that endpoint;
+it is not an identifier and is never uploaded. The first notice does not rewrite
+your API-key configuration.
+
+Disable before running any other command:
+
+```sh
+export TYPEFULLY_TELEMETRY=0
+# Or persist the preference:
+typefully config set telemetry_enabled false
+```
+
+Opt-out takes precedence over the notice marker. Config and completion commands,
+help/version, CI, noninteractive runs, and structured/quiet output do not send.
+Telemetry failures must not fail the user's command. There is no retry queue,
+background process, or retrospective upload of skipped commands.
+
+## Maintainer activation checklist
+
+1. Obtain approval for the specific collector recipient and hosting resource changes.
+2. Verify the account's Workers/D1 plan and spending behavior; do not assume free
+   allowances imply zero possible charges on an existing paid account.
+3. Review the collector deployment guide, disable invocation logs, traces, logpush,
+   and tail consumers, and review infrastructure-level retention separately.
+4. Validate the collector with synthetic payloads only after testing authorization;
+   all repository tests use mocks and must not send actual CLI usage.
+5. Configure the fixed HTTPS endpoint in source. Do not accept a user-controlled
+   endpoint or reuse the authenticated Typefully API client.
+6. Review the disclosure against the deployed recipient, fields, and retention.
+7. Obtain separate approval before merging or publishing a release.
+
+Counts are approximate and can be inflated by clients or bots. Do not add IP-based
+fingerprints or persistent IDs to deduplicate them. See [collector](../collector/)
+for the source and deployment prerequisites.

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typefully-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "CLI for the Typefully API -- manage drafts, threads, and publishing from the terminal"
 readme = "README.md"
 license = "MIT"

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/skills/typefully-cli/SKILL.md

@@ -6,8 +6,8 @@ description: Use this repository's Python Typefully CLI to inspect accounts and
 # Typefully CLI
 
 Run `typefully --help` and the selected command's `--help` before assuming flags.
-This skill describes the maintenance branch's unreleased behavior; older installed
-packages may lack these commands. Do not treat repository documentation as proof
+This skill describes the 0.4.0 release candidate; older installed
+packages may lack these commands or telemetry controls. Do not treat repository documentation as proof
 that the installed package has been upgraded.
 
 ## Access and output
@@ -18,6 +18,16 @@ connected sets; a configured default is not proof it is the intended destination
 `--json` controls **output**, not the request body. Most commands also offer text
 output; `draft-payload` and `media-update` always emit structured JSON.
 
+## Usage telemetry
+
+For automation, set `TYPEFULLY_TELEMETRY=0` explicitly. CI, noninteractive,
+`--json` and quiet runs do not send telemetry. Interactive text runs display a
+notice before any later sending; the notice invocation sends nothing. Disable
+persistently with `typefully config set telemetry_enabled false`. Only version
+and command category are sent, never post content, credentials or account IDs.
+The maintainer-owned host sees source IP; do not call this fully anonymous.
+See `docs/telemetry.md` for the recipient and retention details.
+
 ## Prepare and validate
 
 - Use `draft`/`thread` for ordinary content and `update` for an existing draft.

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/src/typefully_cli/__init__.py

@@ -1,3 +1,3 @@
 """Typefully CLI -- manage drafts, threads, and publishing from the terminal."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/src/typefully_cli/cli.py

@@ -24,6 +24,7 @@ from typefully_cli.exceptions import APIError, TypefullyError
 from typefully_cli.media import upload_media
 from typefully_cli import output as fmt
 from typefully_cli.completions import completions
+from typefully_cli.telemetry import record_usage
 
 
 # --- Shared option decorator ---
@@ -42,6 +43,12 @@ def shared_options(f):
     @click.option("--debug", is_flag=True, hidden=True, help="Log HTTP requests to stderr")
     @wraps(f)
     def wrapper(*args, **kwargs):
+        ctx = click.get_current_context(silent=True)
+        if ctx is not None:
+            record_usage(
+                ctx.find_root().invoked_subcommand,
+                quiet=kwargs.get("quiet", False) or kwargs.get("use_json", False),
+            )
         return f(*args, **kwargs)
 
     return wrapper

{typefully_cli-0.3.0 → typefully_cli-0.4.0}/src/typefully_cli/config.py

@@ -36,6 +36,7 @@ class Config:
     output_format: str = "text"
     default_platforms: str = ""
     timezone: str = ""
+    telemetry_enabled: bool = True
     _path: Path = field(default_factory=_config_path)
 
     @classmethod
@@ -54,6 +55,8 @@ class Config:
         cfg.output_format = defaults.get("output_format", "text")
         cfg.default_platforms = defaults.get("platforms", "")
         cfg.timezone = defaults.get("timezone", "")
+        # Fail closed on malformed values rather than silently enabling collection.
+        cfg.telemetry_enabled = data.get("telemetry", {}).get("enabled", True) is True
         return cfg
 
     def save(self) -> None:
@@ -77,6 +80,7 @@ class Config:
         if self.timezone:
             lines.append(f'timezone = "{_toml_escape(self.timezone)}"')
         lines.append("")
+        lines.extend(["[telemetry]", f"enabled = {str(self.telemetry_enabled).lower()}", ""])
         self._path.write_text("\n".join(lines))
         os.chmod(self._path, 0o600)
 
@@ -86,6 +90,7 @@ class Config:
                 "api_key": _redact(self.api_key) if redact else self.api_key,
             },
             "defaults": {},
+            "telemetry": {"enabled": self.telemetry_enabled},
         }
         if self.onepassword_item:
             d["auth"]["onepassword_item"] = self.onepassword_item
@@ -103,7 +108,7 @@ class Config:
 
 _VALID_KEYS = {
     "api_key", "default_account", "onepassword_item", "output_format",
-    "default_platforms", "timezone",
+    "default_platforms", "timezone", "telemetry_enabled",
 }
 
 _KNOWN_PLATFORMS = {"x", "linkedin", "threads", "bluesky", "mastodon"}
@@ -138,7 +143,11 @@ def config_set(cfg: Config, key: str, value: str) -> dict:
     """Set a config key. Returns the result dict (api_key redacted)."""
     if key not in _VALID_KEYS:
         raise ValueError(f"Unknown config key: {key}. Valid: {', '.join(sorted(_VALID_KEYS))}")
-    if key == "api_key":
+    if key == "telemetry_enabled":
+        if value.lower() not in {"true", "false"}:
+            raise ValueError("telemetry_enabled must be true or false")
+        cfg.telemetry_enabled = value.lower() == "true"
+    elif key == "api_key":
         cfg.api_key = value
     elif key == "default_account":
         cfg.default_account = value

typefully_cli-0.4.0/src/typefully_cli/telemetry.py

@@ -0,0 +1,85 @@
+"""Best-effort aggregate usage with a disclosed, maintainer-owned collector."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from urllib.parse import urlsplit
+
+import click
+import httpx
+
+from typefully_cli import __version__
+from typefully_cli.config import Config
+
+# Maintainer-owned recipient; changing it requires a new visible notice.
+ENDPOINT = "https://typefully-cli-telemetry.dheeraj-personal-site.workers.dev/v1/count"
+NOTICE_REVISION = "1"
+COMMAND_CATEGORIES = {
+    "me": "account", "accounts": "account", "account-detail": "account",
+    "linkedin-resolve": "account",
+    "recent": "drafts", "draft": "drafts", "thread": "drafts", "get": "drafts",
+    "open": "drafts", "update": "drafts", "delete": "drafts", "drafts": "drafts",
+    "batch": "drafts", "plan": "drafts",
+    "publish": "publishing", "schedule": "publishing",
+    "upload": "media", "media-status": "media",
+    "tags": "tags", "tag-create": "tags",
+    "analytics": "analytics", "followers": "analytics",
+    "comments": "comments", "queue": "queue", "queue-schedule": "queue",
+}
+CI_VARIABLES = ("CI", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "BUILD_BUILDID", "TF_BUILD")
+
+
+def record_usage(command: str | None, *, quiet: bool = False) -> None:
+    """Count a known command, never its arguments, without affecting its outcome."""
+    try:
+        category = COMMAND_CATEGORIES.get(command)
+        if not ENDPOINT or category is None or quiet:
+            return
+        if any(os.environ.get(key) for key in CI_VARIABLES):
+            return
+        if os.environ.get("TYPEFULLY_TELEMETRY", "").lower() in {"0", "false", "off", "no"}:
+            return
+        # Never collect from scripts, agents, redirected output, or background jobs.
+        if not all(stream.isatty() for stream in (sys.stdin, sys.stdout, sys.stderr)):
+            return
+        endpoint = urlsplit(ENDPOINT)
+        if endpoint.scheme != "https" or not endpoint.hostname or endpoint.username or endpoint.password:
+            return
+        if endpoint.query or endpoint.fragment or not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", __version__):
+            return
+        cfg = Config.load()
+        if not cfg.telemetry_enabled or cfg.output_format == "json":
+            return
+        marker = cfg._path.parent / "telemetry-notice"
+        notice_key = NOTICE_REVISION + "\n" + ENDPOINT + "\n"
+        if not marker.is_file() or marker.read_text() != notice_key:
+            click.echo(
+                "Typefully CLI usage telemetry is enabled by default for later interactive runs.\n"
+                "Only CLI version and command category are sent to " + ENDPOINT + ".\n"
+                "No content, arguments, API keys, account details, or persistent device ID are sent.\n"
+                "The host sees your network IP; the collector stores only aggregate counts, "
+                "not IPs or user agents. This is activity measurement, not unique users.\n"
+                "Nothing is sent on this run. Before your next run, opt out with\n"
+                "TYPEFULLY_TELEMETRY=0 or: typefully config set telemetry_enabled false",
+                err=True,
+            )
+            # Keep disclosure state separate: never rewrite auth config just to record a notice.
+            marker.parent.mkdir(parents=True, exist_ok=True)
+            with marker.open("w") as handle:
+                os.chmod(marker, 0o600)
+                handle.write(notice_key)
+            return
+        # Dedicated transport: no Typefully auth, proxy credentials, redirects, or retries.
+        with httpx.Client(timeout=0.2, follow_redirects=False, trust_env=False) as client:
+            client.headers.clear()
+            with client.stream(
+                "POST", ENDPOINT,
+                headers={"Content-Type": "application/json", "User-Agent": "typefully-cli"},
+                json={"version": __version__, "category": category},
+            ):
+                pass  # Do not consume a response body or follow server instructions.
+    except Exception:
+        # Telemetry must never fail the user's command or print sensitive transport errors.
+        return

typefully_cli-0.4.0/tests/test_telemetry.py

@@ -0,0 +1,209 @@
+"""Telemetry is exercised exclusively with a fake HTTP client."""
+
+from unittest.mock import MagicMock
+
+import pytest
+import httpx
+
+from click.testing import CliRunner
+
+from typefully_cli import telemetry
+from typefully_cli.cli import cli
+from typefully_cli.config import Config, config_set
+
+REAL_HTTPX_CLIENT = httpx.Client
+
+
+@pytest.fixture
+def setup(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    monkeypatch.delenv("TYPEFULLY_TELEMETRY", raising=False)
+    for key in telemetry.CI_VARIABLES:
+        monkeypatch.delenv(key, raising=False)
+    monkeypatch.setattr(telemetry, "ENDPOINT", "https://collector.invalid/usage")
+    for stream in (telemetry.sys.stdin, telemetry.sys.stdout, telemetry.sys.stderr):
+        monkeypatch.setattr(stream, "isatty", lambda: True)
+    factory = MagicMock()
+    client = factory.return_value.__enter__.return_value
+    monkeypatch.setattr(telemetry.httpx, "Client", factory)
+    return tmp_path / "typefully" / "telemetry-notice", factory, client
+
+
+def test_first_notice_no_send_then_exact_payload(setup, capsys, monkeypatch):
+    for stream in (telemetry.sys.stdin, telemetry.sys.stdout, telemetry.sys.stderr):
+        monkeypatch.setattr(stream, "isatty", lambda: True)
+    marker, factory, client = setup
+    telemetry.record_usage("draft")
+    factory.assert_not_called()
+    text = capsys.readouterr().err
+    assert "Nothing is sent on this run" in text
+    assert "TYPEFULLY_TELEMETRY=0" in text
+    assert "network IP" in text
+    assert marker.exists()
+    assert not (marker.parent / "config.toml").exists()
+    telemetry.record_usage("draft")
+    factory.assert_called_once_with(timeout=0.2, follow_redirects=False, trust_env=False)
+    client.headers.clear.assert_called_once()
+    client.stream.assert_called_once_with(
+        "POST", "https://collector.invalid/usage",
+        headers={"Content-Type": "application/json", "User-Agent": "typefully-cli"},
+        json={"version": "0.4.0", "category": "drafts"},
+    )
+
+
+@pytest.mark.parametrize("setting", ["0", "false", "off", "no", "FALSE"])
+def test_environment_optout(setup, monkeypatch, setting):
+    marker, factory, _ = setup
+    monkeypatch.setenv("TYPEFULLY_TELEMETRY", setting)
+    telemetry.record_usage("draft")
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+def test_config_optout_cannot_be_overridden_by_env(setup, monkeypatch):
+    marker, factory, _ = setup
+    cfg = Config.load()
+    config_set(cfg, "telemetry_enabled", "false")
+    monkeypatch.setenv("TYPEFULLY_TELEMETRY", "1")
+    telemetry.record_usage("draft")
+    assert Config.load().telemetry_enabled is False
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+@pytest.mark.parametrize("key", telemetry.CI_VARIABLES)
+def test_ci_always_skipped_even_with_marker(setup, monkeypatch, key):
+    _, factory, _ = setup
+    telemetry.record_usage("draft")
+    monkeypatch.setenv(key, "true")
+    telemetry.record_usage("draft")
+    factory.assert_not_called()
+
+
+@pytest.mark.parametrize("stream", ["stdin", "stdout", "stderr"])
+def test_noninteractive_always_skipped(setup, monkeypatch, stream):
+    _, factory, _ = setup
+    telemetry.record_usage("draft")
+    monkeypatch.setattr(getattr(telemetry.sys, stream), "isatty", lambda: False)
+    telemetry.record_usage("draft")
+    factory.assert_not_called()
+
+
+@pytest.mark.parametrize("command", [None, "config", "completions", "secret text", "help"])
+def test_unknown_and_administrative_commands_excluded(setup, command):
+    marker, factory, _ = setup
+    telemetry.record_usage(command)
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+@pytest.mark.parametrize("endpoint", ["", "http://collector.invalid", "https://u:p@collector.invalid", "https://collector.invalid?q=secret"])
+def test_invalid_or_unapproved_endpoint_is_dormant(setup, monkeypatch, endpoint):
+    marker, factory, _ = setup
+    monkeypatch.setattr(telemetry, "ENDPOINT", endpoint)
+    telemetry.record_usage("draft")
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+def test_changed_recipient_requires_new_notice(setup, monkeypatch):
+    _, factory, _ = setup
+    telemetry.record_usage("draft")
+    monkeypatch.setattr(telemetry, "ENDPOINT", "https://other.invalid/usage")
+    telemetry.record_usage("draft")
+    factory.assert_not_called()
+
+
+def test_quiet_no_notice_no_send(setup):
+    marker, factory, _ = setup
+    telemetry.record_usage("draft", quiet=True)
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+def test_failures_do_not_escape(setup):
+    _, _, client = setup
+    telemetry.record_usage("draft")
+    client.stream.side_effect = RuntimeError("secret")
+    telemetry.record_usage("draft")
+
+
+def test_malformed_config_fails_closed(setup):
+    marker, factory, _ = setup
+    marker.parent.mkdir(parents=True)
+    (marker.parent / "config.toml").write_text('[telemetry]\nenabled = "false"\n')
+    telemetry.record_usage("draft")
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+def test_config_set_boolean_validation(tmp_path):
+    cfg = Config(_path=tmp_path / "config.toml")
+    config_set(cfg, "telemetry_enabled", "false")
+    assert Config.load(cfg._path).to_dict()["telemetry"] == {"enabled": False}
+    with pytest.raises(ValueError):
+        config_set(cfg, "telemetry_enabled", "yes")
+
+
+def test_cli_disabling_config_never_calls_telemetry(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    track = MagicMock()
+    monkeypatch.setattr("typefully_cli.cli.record_usage", track)
+    result = CliRunner().invoke(cli, ["config", "set", "telemetry_enabled", "false"])
+    assert result.exit_code == 0
+    track.assert_not_called()
+    assert Config.load().telemetry_enabled is False
+
+
+def test_cli_only_passes_category_source_and_quiet_flag(monkeypatch):
+    track = MagicMock()
+    monkeypatch.setattr("typefully_cli.cli.record_usage", track)
+    monkeypatch.setattr("typefully_cli.cli._get_client_and_console", MagicMock(side_effect=RuntimeError))
+    CliRunner().invoke(cli, ["draft", "SECRET POST", "--api-key", "SECRET KEY", "--json"])
+    track.assert_called_once_with("draft", quiet=True)
+
+
+def test_configured_json_mode_excluded(setup):
+    marker, factory, _ = setup
+    cfg = Config.load()
+    config_set(cfg, "output_format", "json")
+    telemetry.record_usage("draft")
+    assert not marker.exists()
+    factory.assert_not_called()
+
+
+def test_notice_marker_write_failure_never_sends(setup):
+    marker, factory, _ = setup
+    marker.mkdir(parents=True)
+    telemetry.record_usage("draft")
+    telemetry.record_usage("draft")
+    factory.assert_not_called()
+
+
+def test_actual_transport_has_only_minimal_request_and_no_redirect(setup, monkeypatch):
+    requests = []
+
+    def handler(request):
+        requests.append(request)
+        return httpx.Response(302, headers={"Location": "https://elsewhere.invalid/steal"})
+
+    transport = httpx.MockTransport(handler)
+    monkeypatch.setattr(
+        telemetry.httpx, "Client",
+        lambda **kwargs: REAL_HTTPX_CLIENT(transport=transport, **kwargs),
+    )
+    monkeypatch.setenv("HTTP_PROXY", "http://secret:credential@proxy.invalid")
+    monkeypatch.setenv("TYPEFULLY_API_KEY", "SUPER_SECRET")
+    telemetry.record_usage("draft")
+    telemetry.record_usage("draft")
+    assert len(requests) == 1
+    request = requests[0]
+    assert str(request.url) == "https://collector.invalid/usage"
+    assert request.method == "POST"
+    assert request.content == b'{"version":"0.4.0","category":"drafts"}'
+    assert dict(request.headers) == {
+        "host": "collector.invalid",
+        "content-type": "application/json",
+        "user-agent": "typefully-cli",
+        "content-length": str(len(request.content)),
+    }