@walkeros/server-destination-twitter 4.1.0-next-1778668930820 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +32 -173
  3. package/dist/walkerOS.json +1 -1
  4. package/package.json +6 -5
package/CHANGELOG.md ADDED
@@ -0,0 +1,122 @@
1
+ # @walkeros/server-destination-twitter
2
+
3
+ ## 4.1.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [e155ff8]
8
+ - Updated dependencies [e800974]
9
+ - Updated dependencies [e155ff8]
10
+ - Updated dependencies [1a8f2d7]
11
+ - Updated dependencies [1a8f2d7]
12
+ - Updated dependencies [b276173]
13
+ - Updated dependencies [dd9f5ad]
14
+ - Updated dependencies [c60ef35]
15
+ - Updated dependencies [adeebea]
16
+ - Updated dependencies [13aaeaa]
17
+ - Updated dependencies [e800974]
18
+ - Updated dependencies [adeebea]
19
+ - Updated dependencies [e800974]
20
+ - Updated dependencies [e800974]
21
+ - Updated dependencies [058f7ed]
22
+ - Updated dependencies [28a8ac2]
23
+ - Updated dependencies [fd6076e]
24
+ - @walkeros/core@4.1.0
25
+ - @walkeros/server-core@4.1.0
26
+
27
+ ## 4.0.2
28
+
29
+ ### Patch Changes
30
+
31
+ - Updated dependencies [a6a0ea7]
32
+ - @walkeros/core@4.0.2
33
+ - @walkeros/server-core@4.0.2
34
+
35
+ ## 4.0.1
36
+
37
+ ### Patch Changes
38
+
39
+ - Updated dependencies [381dfe7]
40
+ - Updated dependencies [1524275]
41
+ - Updated dependencies [03d7055]
42
+ - @walkeros/core@4.0.1
43
+ - @walkeros/server-core@4.0.1
44
+
45
+ ## 4.0.0
46
+
47
+ ### Major Changes
48
+
49
+ - 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
50
+ `Entity` shapes.
51
+ - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
52
+ collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
53
+ - `event.version`, `event.group`, `event.count` are removed.
54
+ - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
55
+ New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
56
+ - `source.id` and `source.previous_id` are removed.
57
+ - Browser source now sets `source.url` and `source.referrer`.
58
+ - MCP source sets `source.tool` per emission. CLI source sets
59
+ `source.command`.
60
+ - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
61
+ and `event.context` remain required.
62
+ - Each source self-registers via TypeScript module augmentation of `SourceMap`
63
+ in `@walkeros/core`.
64
+ - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
65
+ part of this release. Telemetry from v4 CLI/MCP will not validate against
66
+ the existing app schema until that follow-up ships.
67
+ - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
68
+ configs using `skip: true` in mapping rules must rename to `silent: true`.
69
+ Hard cut: no legacy alias, the field is gone.
70
+
71
+ ### Patch Changes
72
+
73
+ - Updated dependencies [93ea9c4]
74
+ - Updated dependencies [465775c]
75
+ - Updated dependencies [942a7fe]
76
+ - Updated dependencies [cfc7469]
77
+ - Updated dependencies [8e06b1f]
78
+ - Updated dependencies [3d50dd6]
79
+ - Updated dependencies [1ef33d9]
80
+ - @walkeros/core@4.0.0
81
+ - @walkeros/server-core@4.0.0
82
+
83
+ ## 3.4.2
84
+
85
+ ### Patch Changes
86
+
87
+ - @walkeros/core@3.4.2
88
+ - @walkeros/server-core@3.4.2
89
+
90
+ ## 3.4.1
91
+
92
+ ### Patch Changes
93
+
94
+ - Updated dependencies [12adf24]
95
+ - Updated dependencies [75aa26b]
96
+ - @walkeros/core@3.4.1
97
+ - @walkeros/server-core@3.4.1
98
+
99
+ ## 3.4.0
100
+
101
+ ### Minor Changes
102
+
103
+ - 74940cc: Add X (Twitter) Conversions API server destination
104
+ - 724f97e: Migrate every step example in every walkerOS package to the
105
+ standardized `[callable, ...args][]` shape introduced in `@walkeros/core`.
106
+ Every step example's `out` is now an array of effect tuples whose first
107
+ element is the callable's public SDK name (`'gtag'`, `'analytics.track'`,
108
+ `'fbq'`, `'dataLayer.push'`, `'sendServer'`, `'fetch'`, `'trackClient.track'`,
109
+ `'amplitude.track'`, `'fs.writeFile'`, `'producer.send'`, `'client.xadd'`,
110
+ `'client.send'`, `'dataset.table.insert'`, etc.). Source examples use `'elb'`
111
+ as the callable; transformer examples use the reserved `'return'` keyword;
112
+ store examples use store-operation callables (`'get'`, `'set'`). Tests capture
113
+ real calls on each component's spy and assert against `example.out` directly —
114
+ the hardcoded `PACKAGE_CALLS` registry in the app is no longer consulted
115
+ (emptied; plan #3 removes it structurally).
116
+
117
+ ### Patch Changes
118
+
119
+ - Updated dependencies [74940cc]
120
+ - Updated dependencies [525f5d9]
121
+ - @walkeros/core@3.4.0
122
+ - @walkeros/server-core@3.4.0
package/README.md CHANGED
@@ -1,8 +1,18 @@
1
+ <p align="left">
2
+ <a href="https://www.walkeros.io">
3
+ <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
4
+ </a>
5
+ </p>
6
+
1
7
  # @walkeros/server-destination-twitter
2
8
 
3
- X (Twitter) Conversions API (CAPI) server destination for walkerOS. Streams
4
- conversion events to X via server-to-server HTTPS POST, authenticated with OAuth
5
- 1.0a.
9
+ Server-side event delivery to X's (Twitter's) Conversions API for enhanced ad
10
+ attribution and privacy-compliant conversion tracking.
11
+
12
+ [Documentation](https://www.walkeros.io/docs/destinations/server/twitter) &bull;
13
+ [NPM Package](https://www.npmjs.com/package/@walkeros/server-destination-twitter)
14
+ &bull;
15
+ [Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/twitter)
6
16
 
7
17
  ## Installation
8
18
 
@@ -10,30 +20,18 @@ conversion events to X via server-to-server HTTPS POST, authenticated with OAuth
10
20
  npm install @walkeros/server-destination-twitter
11
21
  ```
12
22
 
13
- ## Prerequisites
14
-
15
- - X Developer account with **Ads API access**
16
- - Project with **AD_MANAGER** or **ACCOUNT_ADMIN** role
17
- - Pre-registered conversion events in **Ads Manager** (provides the `eventId` in
18
- `tw-xxxxx-xxxxx` format)
19
- - OAuth 1.0a credentials (Consumer Key/Secret + Access Token/Secret)
20
-
21
- ## Minimal Config
23
+ ## Quick start
22
24
 
23
25
  ```json
24
26
  {
25
- "destinations": {
26
- "twitter": {
27
- "package": "@walkeros/server-destination-twitter",
28
- "config": {
29
- "consent": { "marketing": true },
30
- "settings": {
31
- "pixelId": "o8z6j",
32
- "eventId": "tw-o8z6j-o8z21",
33
- "consumerKey": "$env:TWITTER_CONSUMER_KEY",
34
- "consumerSecret": "$env:TWITTER_CONSUMER_SECRET",
35
- "accessToken": "$env:TWITTER_ACCESS_TOKEN",
36
- "accessTokenSecret": "$env:TWITTER_ACCESS_TOKEN_SECRET"
27
+ "version": 4,
28
+ "flows": {
29
+ "default": {
30
+ "config": { "platform": "server" },
31
+ "destinations": {
32
+ "twitter": {
33
+ "package": "@walkeros/server-destination-twitter",
34
+ "config": {}
37
35
  }
38
36
  }
39
37
  }
@@ -41,157 +39,18 @@ npm install @walkeros/server-destination-twitter
41
39
  }
42
40
  ```
43
41
 
44
- ## Full Config
45
-
46
- ```json
47
- {
48
- "destinations": {
49
- "twitter": {
50
- "package": "@walkeros/server-destination-twitter",
51
- "config": {
52
- "consent": { "marketing": true },
53
- "settings": {
54
- "pixelId": "o8z6j",
55
- "eventId": "tw-o8z6j-o8z21",
56
- "consumerKey": "$env:TWITTER_CONSUMER_KEY",
57
- "consumerSecret": "$env:TWITTER_CONSUMER_SECRET",
58
- "accessToken": "$env:TWITTER_ACCESS_TOKEN",
59
- "accessTokenSecret": "$env:TWITTER_ACCESS_TOKEN_SECRET",
60
- "apiVersion": "12",
61
- "user_data": {
62
- "email": "user.email",
63
- "phone": "user.phone",
64
- "twclid": "context.twclid",
65
- "ip_address": "context.ip",
66
- "user_agent": "context.userAgent"
67
- }
68
- },
69
- "mapping": {
70
- "order": {
71
- "complete": {
72
- "settings": {
73
- "value": "data.total",
74
- "currency": { "key": "data.currency", "value": "USD" },
75
- "number_items": "data.count"
76
- }
77
- }
78
- },
79
- "form": { "submit": {} }
80
- }
81
- }
82
- }
83
- }
84
- }
85
- ```
86
-
87
- ## Settings
88
-
89
- | Setting | Type | Required | Default | Description |
90
- | ------------------- | -------- | -------- | -------------------------- | ------------------------------------------ |
91
- | `pixelId` | string | yes | - | X Pixel ID in the endpoint URL |
92
- | `eventId` | string | yes | - | Default conversion event ID (`tw-xxx-xxx`) |
93
- | `consumerKey` | string | yes | - | OAuth 1.0a API Key |
94
- | `consumerSecret` | string | yes | - | OAuth 1.0a API Key Secret |
95
- | `accessToken` | string | yes | - | OAuth 1.0a User Access Token |
96
- | `accessTokenSecret` | string | yes | - | OAuth 1.0a User Access Token Secret |
97
- | `apiVersion` | string | no | `"12"` | X Ads API version number |
98
- | `doNotHash` | string[] | no | `[]` | User data fields already hashed upstream |
99
- | `url` | string | no | `"https://ads-api.x.com/"` | API base URL override (for testing) |
100
- | `user_data` | object | no | - | Mapping config for user identifiers |
101
-
102
- ## Mapping Settings
103
-
104
- Per-event overrides via `mapping.settings`:
105
-
106
- | Field | Type | Description |
107
- | -------------- | ------------- | --------------------------------------------------- |
108
- | `eventId` | string | Override the default conversion `eventId` per event |
109
- | `value` | string/number | Conversion monetary value (sent as a string to X) |
110
- | `currency` | string | ISO 4217 currency code |
111
- | `number_items` | number | Integer number of items in the conversion |
112
- | `description` | string | Free-text description of the conversion |
113
-
114
- ## User Identification
115
-
116
- The destination builds an `identifiers` array. Each identifier is a separate
117
- single-key object in the payload.
118
-
119
- Primary identifiers (at least one required):
42
+ ## Documentation
120
43
 
121
- - **`hashed_email`** -- from `event.user.email` or `user_data.email`, SHA-256
122
- hashed (trimmed + lowercased).
123
- - **`hashed_phone_number`** -- from `event.user.phone` or `user_data.phone`,
124
- SHA-256 hashed.
125
- - **`twclid`** -- X click ID (pass-through, **not** hashed). Typically forwarded
126
- from the browser via `context.twclid`.
44
+ Full configuration, mapping, and examples live in the docs:
45
+ **https://www.walkeros.io/docs/destinations/server/twitter**
127
46
 
128
- Secondary identifiers (optional):
47
+ ## Contribute
129
48
 
130
- - **`ip_address`** -- client IP, pass-through.
131
- - **`user_agent`** -- user agent string, pass-through.
132
-
133
- Use `doNotHash: ['email']` or `doNotHash: ['phone']` to skip hashing for values
134
- that are already SHA-256 hashed upstream.
135
-
136
- Events without any primary identifier are silently skipped.
137
-
138
- ## Deduplication
139
-
140
- The walkerOS event `id` is sent as `conversion_id`. When paired with the
141
- browser-side X (Twitter) Pixel, use the same ID on both sides so X can
142
- deduplicate duplicate conversions across web and server signals.
143
-
144
- ## Multi-Event Setup
145
-
146
- Use a single destination with per-event `eventId` overrides:
147
-
148
- ```json
149
- {
150
- "destinations": {
151
- "twitter": {
152
- "package": "@walkeros/server-destination-twitter",
153
- "config": {
154
- "settings": {
155
- "pixelId": "o8z6j",
156
- "eventId": "tw-o8z6j-default-001",
157
- "consumerKey": "$env:TWITTER_CONSUMER_KEY",
158
- "consumerSecret": "$env:TWITTER_CONSUMER_SECRET",
159
- "accessToken": "$env:TWITTER_ACCESS_TOKEN",
160
- "accessTokenSecret": "$env:TWITTER_ACCESS_TOKEN_SECRET"
161
- },
162
- "mapping": {
163
- "order": {
164
- "complete": {
165
- "settings": {
166
- "eventId": { "value": "tw-o8z6j-purchase-01" },
167
- "value": "data.total",
168
- "currency": { "key": "data.currency", "value": "USD" }
169
- }
170
- }
171
- },
172
- "form": {
173
- "submit": {
174
- "settings": {
175
- "eventId": { "value": "tw-o8z6j-lead-01" }
176
- }
177
- }
178
- }
179
- }
180
- }
181
- }
182
- }
183
- }
184
- ```
185
-
186
- ## Consent
187
-
188
- Marketing consent is required. Configure via `config.consent`:
189
-
190
- ```json
191
- "consent": { "marketing": true }
192
- ```
49
+ Feel free to contribute by submitting an
50
+ [issue](https://github.com/elbwalker/walkerOS/issues), starting a
51
+ [discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
52
+ [contact](https://calendly.com/elb-alexander/30min).
193
53
 
194
- ## Links
54
+ ## License
195
55
 
196
- - [X Conversions API docs](https://developer.x.com/en/docs/twitter-ads-api/measurement/api-reference/conversions)
197
- - [walkerOS documentation](https://www.walkeros.io/docs/destinations/server/twitter)
56
+ MIT
package/dist/walkerOS.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$meta": {
3
3
  "package": "@walkeros/server-destination-twitter",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "type": "destination",
6
6
  "platform": [
7
7
  "server"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@walkeros/server-destination-twitter",
3
3
  "description": "X (Twitter) Conversions API server destination for walkerOS",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "license": "MIT",
6
6
  "exports": {
7
7
  ".": {
@@ -22,7 +22,8 @@
22
22
  }
23
23
  },
24
24
  "files": [
25
- "dist/**"
25
+ "dist/**",
26
+ "CHANGELOG.md"
26
27
  ],
27
28
  "scripts": {
28
29
  "build": "tsup --silent",
@@ -34,12 +35,12 @@
34
35
  "update": "npx npm-check-updates -u && npm update"
35
36
  },
36
37
  "dependencies": {
37
- "@walkeros/core": "4.1.0-next-1778668930820",
38
- "@walkeros/server-core": "4.1.0-next-1778668930820",
38
+ "@walkeros/core": "4.1.0",
39
+ "@walkeros/server-core": "4.1.0",
39
40
  "oauth-1.0a": "^2.2.6"
40
41
  },
41
42
  "devDependencies": {
42
- "@walkeros/collector": "4.1.0-next-1778668930820"
43
+ "@walkeros/collector": "4.1.0"
43
44
  },
44
45
  "repository": {
45
46
  "url": "git+https://github.com/elbwalker/walkerOS.git",