Build Telegram-to-Typefully social draft assistant

[alexeygrigorev]

Build Telegram-to-Typefully social draft assistant

Status: automated acceptance passed - pending HUMAN external checks
Tags: enhancement, assistant, work-engine, backend, infra, P1
Depends on: None
Blocks: None

Scope

Implement the first working assistant slice for social post drafting:

• A local/testable workflow accepts a mock Telegram message that asks for social posts and turns it into a social drafting assistant run.
• The assistant uses z.ai through the Anthropic-compatible Messages API with ZAI_API_KEY and default model glm-5.2.
• The assistant drafts X/Twitter and LinkedIn copy in the style of historical Typefully posts.
• The workflow creates a Typefully saved draft, not a scheduled or published post.
• The assistant chooses the target Typefully social set/account from the request, supporting Alexey / Al_Grigor and DataTalksClub. If the target is ambiguous, it must fail safely or produce a review-required result instead of writing to the wrong account.
• Real Telegram webhook delivery and real external writes remain behind human/manual verification. The required automated proof is local with mocked Telegram input and mocked z.ai/Typefully clients.

Relevant local surfaces:

• Existing Telegram intake route: work-engine/src/routes/telegram.ts
• Existing assistant job API/lifecycle: work-engine/src/routes/assistantJobs.ts, work-engine/src/db/assistantJobs.ts
• Existing Telegram tests: work-engine/tests/telegram.test.ts
• Typefully helper scripts: scripts/typefully/
• z.ai reference: ../ai-engineering-field-guide/job-market/_internal/extract_llm.py

The current uncommitted scripts/typefully/ utilities are supporting context, not required product scope. The engineer may reuse or adapt small pieces if that is the lowest-risk path, but this issue should not depend on committing the full export/analysis tooling. Historical style examples used by tests must be sanitized fixtures or generated test data, not private .tmp/typefully* exports.

Acceptance Criteria

• A mock Telegram social drafting request can be processed locally into a social drafting assistant run without requiring a real Telegram webhook.
• The assistant request captures the source Telegram text, target account/social set, target platforms (x and linkedin), requested intent, and review status in DataOps state or an assistant output artifact.
• The z.ai client is implemented behind a small interface that is mockable in tests and uses the Anthropic-compatible Messages API with:
  • ZAI_API_KEY
  • default model glm-5.2
  • base URL compatible with the reference implementation (https://api.z.ai/api/anthropic)
  • no secret logging or persistence
• The Typefully draft client is implemented behind a small interface that is mockable in tests, creates saved drafts only, and never schedules or publishes.
• Account selection supports at least these explicit hints:
  • Alexey / Al_Grigor
  • DataTalksClub / DTC
• Ambiguous account selection does not create a Typefully draft and leaves a clear review/error state.
• Prompt/context assembly includes historical style examples for both X/Twitter and LinkedIn, separated by account where possible. Test fixtures must be sanitized and public-safe.
• Automated tests cover a successful mocked Telegram-to-Typefully draft flow for Alexey / Al_Grigor.
• Automated tests cover a successful mocked Telegram-to-Typefully draft flow for DataTalksClub.
• Automated tests cover ambiguous account handling and verify no Typefully write happens.
• Automated tests cover z.ai and Typefully failure handling without leaking ZAI_API_KEY, TYPEFULLY_API_KEY, Telegram tokens, private draft URLs, or raw private exports in logs/errors.
• Local configuration/readiness is documented for ZAI_API_KEY, Typefully API credentials/social-set identifiers, and Telegram webhook variables needed for real integration.
• [HUMAN] With a real ZAI_API_KEY, an operator may run the assistant against z.ai and inspect the generated copy quality.
• [HUMAN] With a real Typefully key, an operator may create one saved Typefully draft and confirm it is unscheduled/unpublished and attached to the intended account.
• [HUMAN] Real Telegram webhook delivery, bot/channel/group permissions, and deployed webhook secret setup are verified by an operator before production use.

Test Scenarios

Scenario: Alexey draft from mock Telegram

Given: mocked z.ai and Typefully clients, sanitized Alexey / Al_Grigor X and LinkedIn style examples, and a mock Telegram message that asks for Alexey social posts
When: the local assistant workflow processes the message
Then: it selects Alexey / Al_Grigor, asks z.ai for draft copy, creates a mocked Typefully saved draft for X and LinkedIn, and records the draft metadata without secrets.

Scenario: DataTalksClub draft from mock Telegram

Given: mocked z.ai and Typefully clients, sanitized DataTalksClub X and LinkedIn style examples, and a mock Telegram message that asks for DTC/DataTalksClub social posts
When: the local assistant workflow processes the message
Then: it selects the DataTalksClub social set, drafts account-appropriate X and LinkedIn copy, creates a mocked Typefully saved draft, and records the review-required result.

Scenario: Ambiguous account

Given: mocked z.ai and Typefully clients and a mock Telegram message that does not identify Alexey or DataTalksClub
When: the local assistant workflow processes the message
Then: it does not call Typefully, records a clear ambiguous-account state, and leaves the item/job ready for human clarification.

Scenario: Provider failure

Given: mocked z.ai or Typefully failures
When: the assistant workflow runs
Then: the job/result records a sanitized failure state, no secret values or private draft URLs appear in persisted metadata or logs, and retries/manual review remain possible according to the existing assistant job lifecycle.

Required Verification

• npm --prefix work-engine test
• npm --prefix work-engine run typecheck
• npm --prefix work-engine run build
• Focused tests for the new mocked Telegram/social assistant flow.
• npm --prefix work-engine run test:e2e only if the implementation changes operator UI, route behavior beyond unit/API coverage, or end-to-end workflow behavior that cannot be proven by the focused tests. If skipped, Tester must explain why the focused API/unit coverage is enough for this backend assistant slice.
• Assistant Engineer review is recommended for prompt/tool boundaries before Tester review because this introduces a new assistant workflow.

Out of Scope

• Publishing or scheduling posts in Typefully.
• Real Telegram webhook deployment, bot setup, channel/group permission setup, or production webhook verification except as [HUMAN] readiness checks.
• Real external writes during automated tests.
• Committing raw Typefully exports, private draft URLs, private social copy archives, credentials, screenshots, sponsor/finance/contact details, or operational SOPs into this public repo.
• Migrating all scripts/typefully/ export/analysis utilities into production code.
• Frontend UI changes unless the engineer finds a minimal existing assistant-job surface update necessary for visibility.
• Changes to ../dtc-operations, ../datatasks, ../podcast-assistant, or ../ai-engineering-field-guide.

Dependencies

• Local development requires ZAI_API_KEY only for optional real z.ai verification. Automated tests must use mocks.
• Real Typefully draft creation requires Typefully API credentials and known social-set identifiers for Alexey / Al_Grigor and DataTalksClub. Automated tests must use mocks.
• Production use will require deployed secret/config plumbing for z.ai, Typefully, and Telegram webhook settings through the existing DataOps deployment path; do not hardcode secrets or depend on another app's local secret store.

[alexeygrigorev]

Additional intake from Alexey:

• Use glm-5.2 for the z.ai Anthropic-compatible assistant, not the PocketShell default glm-4.6 found in local examples.
• For local verification, Alexey says the existing z.ai key from PocketShell may be used. Do not print or commit this key. PM/SWE should still define the DataOps production secret/config path explicitly rather than depending on another app's local secret store.

[alexeygrigorev]

Additional z.ai implementation references from ../ai-engineering-field-guide:

• job-market/_internal/extract_llm.py uses the Python anthropic.Anthropic client against z.ai.
• Env/config names used there:
  • ZAI_API_KEY
  • optional ZAI_MODEL, defaulting to glm-5.2
  • optional ZAI_MAX_TOKENS, defaulting to 4096
  • optional ZAI_TIMEOUT, defaulting to 120
  • optional retry knobs such as ZAI_CLIENT_MAX_RETRIES and ZAI_MAX_EXTRACTION_RETRIES
• Base URL in that repo is https://api.z.ai/api/anthropic.
• Call shape uses Anthropic Messages API with messages.create(...), system, messages, and tool use via tools plus tool_choice.
• job-market/_internal/PIPELINE.md documents ZAI_API_KEY as the Z.ai Anthropic-compatible key.

This should supersede the older PocketShell default model example: DataOps social drafting assistant should use glm-5.2 unless the groomed issue explicitly makes it configurable.

[alexeygrigorev]

PM grooming complete.

I scoped this to the first implementation-ready slice: a locally testable Telegram-to-social-draft assistant that can create a Typefully saved draft through mocked providers, with optional human checks for real z.ai and Typefully credentials.

Key product decisions:

• Use z.ai through the Anthropic-compatible Messages API with ZAI_API_KEY, default model glm-5.2, and base URL matching the field-guide reference.
• Create saved Typefully drafts only; no publishing or scheduling.
• Support account selection between Alexey / Al_Grigor and DataTalksClub, and fail safely when ambiguous.
• Historical Typefully style examples are required for both X/Twitter and LinkedIn, but must be sanitized fixtures or generated test data.
• Existing uncommitted scripts/typefully/ utilities are supporting context, not required scope. Reuse small pieces only if helpful; do not make the issue depend on committing the full export tooling.
• Real Telegram delivery/webhook setup and real external writes are [HUMAN] checks, not automated acceptance gates.

Ready for Software Engineer. Assistant Engineer review is recommended before Tester review because this adds a new assistant workflow and provider/tool boundary.

[alexeygrigorev]

SWE implementation handoff

Implemented the first backend assistant slice for mock Telegram -> z.ai -> Typefully saved draft.

Changed files:

• work-engine/src/assistant/socialDraftAssistant.ts: social drafting route/service, z.ai Anthropic-compatible client, Typefully saved-draft client, account selection, safe ambiguous-account handling, redacted provider failure handling, test client injection.
• work-engine/src/assistant/socialStyleExamples.ts: sanitized style fixtures for Alexey / Al_Grigor and DataTalksClub across X and LinkedIn.
• work-engine/src/router.ts: routes /api/assistant-social-drafts/mock-telegram.
• work-engine/tests/api-social-draft-assistant.test.ts: mocked Alexey/DTC success flows, ambiguous account no-write flow, provider secret-redaction flow, z.ai defaults, Typefully saved-draft request shape/no publish_at.
• work-engine/README.md: local readiness/config docs for z.ai, Typefully, and Telegram variables.

Verification:

• NODE_ENV=test SKIP_AUTH=true node --import tsx --test work-engine/tests/api-social-draft-assistant.test.ts -> 6 pass, 0 fail.
• npm --prefix work-engine run typecheck -> pass.
• npm --prefix work-engine run build -> pass.
• npm --prefix work-engine test -> 706 pass, 0 fail.

Notes:

• Checked .env remains ignored via git check-ignore -v .env; no env file or real key committed.
• Verified the current Typefully API docs for POST /v2/social-sets/{social_set_id}/drafts; the implementation sends platforms, optional draft_title/scratchpad_text, share: false, and omits publish_at so drafts are saved only.
• scripts/typefully/ remains untracked supporting utility work from the earlier export/analysis request; it is not required by this issue.
• E2E skipped because this is a backend/API assistant slice with no operator UI changes; route behavior and provider boundaries are covered by focused API/unit tests.

Remaining gates:

• Assistant Engineer review recommended for prompt/tool boundaries.
• Tester review.
• [HUMAN] real z.ai copy-quality check, real Typefully saved-draft check, and real Telegram webhook/bot permission verification.