n8n-nodes-postwire 0.2.3 → 0.3.0

package/README.md

@@ -1,59 +1,117 @@
 # n8n-nodes-postwire
 
-Publish one idea to every social network from n8n — with **a different post written for each one**, not the same text pasted everywhere.
+Publish one idea to every social network from n8n — with **a different post written for each network**, not the same text pasted everywhere.
 
-[PostWire](https://postwire.io) handles the part that usually stops an n8n workflow: TikTok, Instagram and YouTube all require an approved developer app, and TikTok's App Review asks for a demo video of the integration you cannot build until you are approved. PostWire already holds those approvals, so connecting an account is a single OAuth click.
-
-## What the node does
-
-| Operation | What it does |
-|---|---|
-| **Write a Post per Network** | One idea in, a native draft out per network — correct length, hashtag conventions, an SEO title and tags for YouTube, a hook-first caption for TikTok, link-in-comment for LinkedIn. Does not publish. |
-| **Publish** | Sends to every selected network in one call. |
-| **Write and Publish** | Both, in one node. |
-| **Schedule** | Queues a post for later, and validates it **now** — so a missing video surfaces while you are watching, not at 7am tomorrow. |
-| **Get Account** | Plan, posts used this month, connected accounts. |
+This is the official n8n node for [PostWire](https://postwire.io), maintained by the PostWire team. PostWire already holds the platform approvals TikTok, Instagram (Meta) and YouTube require for publishing apps, so connecting an account is one OAuth click — there is no developer app or App Review on your side.
 
 Networks: TikTok · Instagram · YouTube · LinkedIn · X · Facebook · Reddit · Bluesky · Mastodon · Telegram · Discord.
 
 ## Install
 
-**n8n Cloud** — Settings → Community nodes → Install → `n8n-nodes-postwire`
+**n8n Cloud and self-hosted** — Settings → Community nodes → Install → `n8n-nodes-postwire`.
 
-**Self-hosted** — Settings → Community nodes → Install, or:
+Self-hosted, from the command line:
 
 ```bash
-npm install n8n-nodes-postwire
+cd ~/.n8n/nodes && npm install n8n-nodes-postwire
 ```
 
 ## Credentials
 
-1. Get a free API key at [postwire.io/dashboard.html](https://postwire.io/dashboard.html) and connect the accounts you want to post to.
-2. In n8n, create a **PostWire API** credential and paste the key.
-3. Press **Test** — it calls `/api/me` and returns your plan and connected accounts, so a wrong key fails now rather than at publish time.
+1. Create a free account at [postwire.io/dashboard.html](https://postwire.io/dashboard.html) and connect the networks you want to post to (Accounts).
+2. Copy your API key from **API & MCP**.
+3. In n8n, create a **PostWire API** credential, paste the key and press **Test** — it calls `GET /api/me`, so a wrong key fails now rather than at publish time.
 
 Free plan: one brand with every network it connects, 30 posts a month, no card.
 
-## Nothing half-publishes
+## Resources and operations
+
+| Resource | Operation | What it does |
+|---|---|---|
+| **Post** | **Publish** | Publishes now to one or more networks. *Content* can be **Smart Distribute** (one idea in, a native post per network), **Same Text on Every Network**, or **Drafts From a Previous Step** (for approval flows). |
+| | **Write Drafts** | Preview only: writes a native draft per network — right length, hook, hashtags, YouTube title and tags — and publishes nothing. Also returns a readable `preview` for Slack/Telegram/email approval. |
+| | **Schedule** | Queues a post for later. Connections and media are checked **now**, so a missing video shows up while you watch, not at 7am tomorrow. |
+| | **Plan Week** | One topic in, up to five days of different posts out (a lesson, a mistake, a number, a question, behind the scenes), already scheduled one per day at the hour you choose, in the workflow's time zone. Text networks only. |
+| | **Get Status** | Whether a TikTok or YouTube upload has finished processing. |
+| **Scheduled Post** | Get Many · Update · Cancel | Read the queue, move a post to another time, or cancel it. |
+| **Brand** | Get Many · Create · Rename · Delete | A brand is one business with all its networks — what PostWire plans count. |
+| **Connection** | Get Many · Check Health · Create Connect Link | See connected accounts, ask a network whether a connection can still publish, or create a one-hour link a client can use to connect *their* account to your PostWire (agencies). |
+| **Account** | Get | Plan, posts used this month, connected networks. |
+| **Media** | Upload | Hosts a binary from a previous node and returns a public URL the networks can download. |
+
+The node is also available as an **AI agent tool** (`usableAsTool`): attach it to an AI Agent node and the agent can write drafts or publish.
+
+## Media: the part that usually fails
+
+TikTok and YouTube only publish video; Instagram needs a photo or a video. The networks **download the file from a link**, with no login — so the most common failure is a link that opens a page instead of the file.
 
-The most common way a cross-posting workflow goes wrong is a partial send: you ask for four networks and two go out. This node checks before anything is published — that each network is connected, that the caption is inside that platform's character limit, and that video networks actually have a video. If any of them would fail, the whole call is refused and the error tells you which one and what to change.
+- **Media → Binary File** (recommended): put a Google Drive *Download*, HTTP Request or Read File node before PostWire. The node uploads the file (up to 50 MB) and PostWire hosts it for 30 days.
+- **Media → URL**: a public `https://` link straight to the `.mp4`/`.jpg` (up to 1 GB). Before anything is sent, the node checks the link the way the networks will: reachable without a login, a file and not a web page, under 1 GB, and a video when a video network is selected. Google Drive, Dropbox (`dl=0`), OneDrive and "link to a post" URLs are recognised and the error says exactly what to change.
 
-The node also validates media in the editor, so `youtube will not accept a post without a video` appears before you run the workflow rather than after.
+## Nothing half-publishes, nothing double-posts
+
+- PostWire refuses the whole call if any selected network is not connected, instead of publishing to half of them.
+- Shared text over a network's limit is shortened for that network (X 280, Bluesky 300, Mastodon 500…) instead of failing.
+- **Idempotency Key** (Options): PostWire refuses a second post with the same key for 24 hours. With Smart Distribute the node sets one automatically per execution, so n8n's *Retry On Fail* can never post the same thing twice.
+- **Dry Run** (Options): checks connections, media and length and returns exactly what would go out, per network — without publishing.
 
 ## Output
 
-**Publish** returns one n8n item per network, so you can wire a Filter or IF node straight onto the failures:
+**Publish** returns one item per network, so a Filter or IF node can act on failures alone:
 
 ```json
-{ "ok": true,  "platform": "x",       "id": "1934…", "url": "https://x.com/…" }
-{ "ok": false, "platform": "youtube", "error": "youtube needs a video…", "code": "media_required" }
+{ "ok": true,  "platform": "x", "id": "1934…", "url": "https://x.com/…" }
+{ "ok": false, "platform": "youtube", "error": "…", "hint": "YouTube could not download the media. It must be a public https link…" }
 ```
 
-**Write a Post per Network** returns `{ drafts: { "<platform>": { text, title?, tags? } } }`.
+If **no** network was published, the step fails (so a scheduled workflow cannot go silent for weeks), with the reason and the fix.
+
+**Write Drafts** returns:
+
+```json
+{
+  "drafts": { "linkedin": { "text": "…" }, "youtube": { "text": "…", "title": "…", "tags": ["…"] } },
+  "platforms": ["linkedin", "youtube"],
+  "preview": "*LinkedIn*\n…\n\n*YouTube*\n…"
+}
+```
+
+Map `{{ $json.drafts }}` into a later Publish with *Content → Drafts From a Previous Step*.
+
+## Errors say what to do
+
+Every refusal from the API carries a code, and the node turns it into a message plus the fix:
+
+| Code | What you see |
+|---|---|
+| `not_connected` | Which network, and where to connect it (or send a client a Connect Link) |
+| `media_required` | Which network needs a video/photo, and how to add one |
+| `media_unreachable` | Why PostWire could not download the file (403, 404, a Drive page…) — nothing was published |
+| `too_long` | The limit and how far over it the text is |
+| `limit_reached`, `brand_limit_reached` | The plan limit and the upgrade link |
+| `duplicate_post` | That the post was already sent moments ago and was not sent twice |
+| 401 | Fix the API key in the credential |
+| 429 | Daily AI-draft cap per plan, or a burst limit — wait or add a Wait node |
+
+## Examples
+
+**RSS → a native post per network**
+
+`RSS Feed Trigger` → `PostWire: Post → Publish` (Content: Smart Distribute, Idea: `{{ $json.title }} — {{ $json.contentSnippet }} {{ $json.link }}`, Networks: LinkedIn, X, Bluesky, Options → Idempotency Key: `{{ $json.guid }}`).
+
+**Google Drive video → TikTok, Reels and Shorts**
+
+`Google Drive Trigger` → `Google Drive: Download` → `PostWire: Post → Publish` (Media: Binary File, Networks: TikTok, Instagram, YouTube, Idea: `{{ $json.name }}`).
+
+**Approve in Slack before anything goes out**
+
+`PostWire: Write Drafts` → `Slack: Send and Wait for Approval` (message: `{{ $json.preview }}`) → `IF approved` → `PostWire: Publish` (Content: Drafts From a Previous Step, Drafts: `{{ $('Write drafts').item.json.drafts }}`).
+
+Ready-to-import templates: [n8n.io/creators/postwire](https://n8n.io/creators/postwire/).
 
 ## Pricing
 
-Priced per **brand** — one business with all of its networks — not per channel or per social account. Adding a fifth network to a brand never changes the bill.
+Priced per **brand** — one business with all of its networks — not per channel. Adding a fifth network to a brand never changes the bill.
 
 | | Brands | Posts/month | |
 |---|---|---|---|
@@ -62,9 +120,15 @@ Priced per **brand** — one business with all of its networks — not per chann
 | Pro | 10 | 2,000 | $29/mo |
 | Agency | 50 | 15,000 | $99/mo |
 
-## Also available
+## Compatibility
+
+Tested with n8n 2.40. Workflows built with version 1 of the node (package 0.1.x–0.2.x) keep working unchanged; new nodes use version 2.
+
+## Resources
 
-A REST API and a hosted MCP server (`https://postwire.io/api/mcp`) for AI agents in Claude, Cursor or VS Code. See [postwire.io/mcp](https://postwire.io/mcp/).
+- [PostWire API reference (OpenAPI)](https://postwire.io/openapi.json)
+- [n8n + PostWire guide](https://postwire.io/n8n-social-media-automation/)
+- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
 
 ## License
 

package/dist/credentials/PostWireApi.credentials.js

@@ -1,14 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostWireApi = void 0;
-// PostWire authenticates with a single bearer key. The `test` block below is what makes n8n's
-// "Test connection" button meaningful: /api/me returns the plan, the month's usage and the
-// connected accounts, so a wrong key fails immediately instead of at publish time.
 class PostWireApi {
     constructor() {
         this.name = 'postWireApi';
         this.displayName = 'PostWire API';
-        // Both variants: the badge is a dark square, which disappears against n8n's dark theme.
         this.icon = { light: 'file:postwire.svg', dark: 'file:postwire.dark.svg' };
         this.documentationUrl = 'https://postwire.io/n8n-social-media-automation/';
         this.properties = [
@@ -28,8 +24,6 @@ class PostWireApi {
             properties: {
                 headers: {
                     Authorization: '=Bearer {{$credentials.apiKey}}',
-                    // Read server-side to tell n8n traffic apart from the dashboard. npm download counts
-                    // turned out to be a scanner floor, so this header is the only honest usage signal.
                     'X-PostWire-Source': 'n8n',
                 },
             },
@@ -44,3 +38,4 @@ class PostWireApi {
     }
 }
 exports.PostWireApi = PostWireApi;
+//# sourceMappingURL=PostWireApi.credentials.js.map

package/dist/credentials/PostWireApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostWireApi.credentials.js","sourceRoot":"","sources":["../../credentials/PostWireApi.credentials.ts"],"names":[],"mappings":";;;AAWA,MAAa,WAAW;IAAxB;QACC,SAAI,GAAG,aAAa,CAAC;QAErB,gBAAW,GAAG,cAAc,CAAC;QAG7B,SAAI,GAAS,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;QAE5E,qBAAgB,GAAG,kDAAkD,CAAC;QAEtE,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,aAAa;gBAC1B,WAAW,EACV,4KAA4K;aAC7K;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,aAAa,EAAE,iCAAiC;oBAGhD,mBAAmB,EAAE,KAAK;iBAC1B;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,qBAAqB;gBAC9B,GAAG,EAAE,SAAS;gBACd,MAAM,EAAE,KAAK;aACb;SACD,CAAC;IACH,CAAC;CAAA;AA3CD,kCA2CC"}

package/dist/nodes/PostWire/Description.d.ts

@@ -0,0 +1,9 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const resourceProperty: INodeProperties;
+export declare const operationProperties: INodeProperties[];
+export declare const postProperties: INodeProperties[];
+export declare const scheduledPostProperties: INodeProperties[];
+export declare const brandProperties: INodeProperties[];
+export declare const connectionProperties: INodeProperties[];
+export declare const accountProperties: INodeProperties[];
+export declare const mediaProperties: INodeProperties[];