@teever/ez-hook 0.3.5 → 0.3.6

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 (2) hide show
  1. package/README.md +231 -147
  2. package/package.json +16 -22
package/README.md CHANGED
@@ -1,147 +1,231 @@
1
- <div align="center">
2
- <h1>EZ Hook - TypeScript/JavaScript</h1>
3
- </div>
4
-
5
- Zero dependency, TypeScript/JavaScript library for sending Discord webhooks.
6
- <br>
7
- Useful for edge runtimes, Cloudflare Workers, Vercel, Deno, etc.
8
- <br>
9
- Create embeds using builder methods with flexible parameter options - pass objects or individual values for customization.
10
- <br>
11
- ### Built-in Input Validation Errors
12
-
13
- The hook throws validation errors in the following cases:
14
-
15
- - **Size Constraints**:
16
- - Content exceeds maximum allowed length
17
- - Content is shorter than minimum required length
18
- - Field size is larger than permitted limit
19
- - Field size is smaller than required minimum
20
-
21
- - **Invalid Content**:
22
- - Content format doesn't match required pattern
23
- - Content contains invalid characters
24
- - Content structure violates specified rules
25
-
26
- These validations comply with Discord's limits.
27
-
28
- ### Discord Webhook Limits
29
-
30
- - **Content Limits**:
31
- - Message content: 2000 characters
32
- - Embed title: 256 characters
33
- - Embed description: 4096 characters
34
- - Embed fields: Up to 25 fields
35
- - Embed field name: 256 characters
36
- - Embed field value: 1024 characters
37
- - Embed footer text: 2048 characters
38
- - Embed author name: 256 characters
39
- - Total embeds per message: 10
40
- - Total character limit across all embeds: 6000 characters
41
-
42
- - **Media Limits**:
43
- - Image URLs: 2048 characters
44
- - Thumbnail URLs: 2048 characters
45
- - Author icon URLs: 2048 characters
46
- - Footer icon URLs: 2048 characters
47
-
48
- - **Rate Limits**:
49
- - Default rate limit: 30 requests per minute per webhook
50
- - Responses include retry-after header when rate limited
51
-
52
- These limits are enforced by Discord's API and this library validates inputs against these limits to prevent API errors.
53
-
54
- ## Install
55
-
56
- `deno add @teever/ez-hook`
57
- <br>
58
- `npx jsr add @teever/ez-hook`
59
- <br>
60
- `yarn dlx jsr add @teever/ez-hook`
61
- <br>
62
- `pnpm dlx jsr add @teever/ez-hook`
63
- <br>
64
- `bunx jsr add @teever/ez-hook`
65
-
66
- # Features
67
-
68
- - Zero dependencies
69
- - TypeScript support
70
- - Automatic retry on rate limits and server errors
71
- - Configurable retry behavior
72
- - Fluent builder API
73
- - Overloaded methods for simpler usage
74
-
75
- # Example
76
-
77
- ## Basic Use
78
-
79
- ```ts
80
- import { Webhook } from '@teever/ez-hook'
81
-
82
- // Optional retry configuration
83
- const retryConfig = {
84
- maxRetries: 3, // Maximum number of retries
85
- baseDelay: 1000, // Base delay in ms (1 second)
86
- maxDelay: 60000 // Maximum delay in ms (60 seconds)
87
- } // Also the default configuration
88
-
89
- const hook = new Webhook('https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz', retryConfig)
90
-
91
- hook
92
- .setUsername('Username')
93
- .setContent('Lorem ipsum dolor sit amet, consectetur adipiscing elit.')
94
-
95
- hook.send()
96
- ```
97
-
98
- ## Custom Embeds (Rich Message)
99
-
100
- ```ts
101
- import { Embed, Webhook } from '@teever/ez-hook'
102
-
103
- const hook = new Webhook('https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz')
104
-
105
- const embed = new Embed()
106
- embed
107
- .setTitle('Embed Title')
108
- .setDescription('Embed Description')
109
- // Use hex string or number for color
110
- .setColor('#ffffff') // (Note: must be prefixed with #)
111
- // Example number for color
112
- .setColor(12345)
113
- // Simple method overload
114
- .setThumbnail('https://example.com/image.png')
115
- // Or use full object
116
- .setThumbnail({
117
- url: 'https://example.com/image.png',
118
- height: 100,
119
- width: 100
120
- })
121
- // Simple author setting
122
- .setAuthor('Author Name', 'https://discord.com', 'https://example.com/icon.png')
123
- // Or use full object
124
- .setAuthor({
125
- name: 'Author Name',
126
- icon_url: 'https://example.com/icon.png',
127
- url: 'https://discord.com'
128
- })
129
- // Simple footer setting
130
- .setFooter('Footer Text', 'https://example.com/icon.png')
131
- // Or use full object
132
- .setFooter({
133
- text: 'Footer Text',
134
- icon_url: 'https://example.com/icon.png'
135
- })
136
- .setTimestamp()
137
- // Simple field adding
138
- .addField('Field 1', 'Value 1', true)
139
- // Or use full object
140
- .addField({
141
- name: 'Field 2',
142
- value: 'Value 2',
143
- inline: true
144
- })
145
-
146
- const success = await hook.addEmbed(embed).send()
147
- ```
1
+ <div align="center">
2
+ <h1>EZ Hook - TypeScript/JavaScript</h1>
3
+ </div>
4
+
5
+ Zero dependency, TypeScript/JavaScript library for sending Discord webhooks.
6
+ <br>
7
+ Useful for edge runtimes, Cloudflare Workers, Vercel, Deno, etc.
8
+ <br>
9
+ Create embeds using builder methods with flexible parameter options - pass objects or individual values for customization.
10
+ <br>
11
+ ### Built-in Input Validation Errors
12
+
13
+ The hook throws validation errors in the following cases:
14
+
15
+ - **Size Constraints**:
16
+ - Content exceeds maximum allowed length
17
+ - Content is shorter than minimum required length
18
+ - Field size is larger than permitted limit
19
+ - Field size is smaller than required minimum
20
+
21
+ - **Invalid Content**:
22
+ - Content format doesn't match required pattern
23
+ - Content contains invalid characters
24
+ - Content structure violates specified rules
25
+
26
+ These validations comply with Discord's limits.
27
+
28
+ ### Discord Webhook Limits
29
+
30
+ - **Content Limits**:
31
+ - Message content: 2000 characters
32
+ - Embed title: 256 characters
33
+ - Embed description: 4096 characters
34
+ - Embed fields: Up to 25 fields
35
+ - Embed field name: 256 characters
36
+ - Embed field value: 1024 characters
37
+ - Embed footer text: 2048 characters
38
+ - Embed author name: 256 characters
39
+ - Total embeds per message: 10
40
+ - Total character limit across all embeds: 6000 characters
41
+
42
+ - **Media Limits**:
43
+ - Image URLs: 2048 characters
44
+ - Thumbnail URLs: 2048 characters
45
+ - Author icon URLs: 2048 characters
46
+ - Footer icon URLs: 2048 characters
47
+
48
+ - **Rate Limits**:
49
+ - Default rate limit: 30 requests per minute per webhook
50
+ - Responses include retry-after header when rate limited
51
+
52
+ These limits are enforced by Discord's API and this library validates inputs against these limits to prevent API errors.
53
+
54
+ ## Install
55
+
56
+ Install from npm:
57
+
58
+ - `npm install @teever/ez-hook`
59
+ - `pnpm add @teever/ez-hook`
60
+ - `yarn add @teever/ez-hook`
61
+ - `bun add @teever/ez-hook`
62
+
63
+ Install from JSR:
64
+
65
+ - `deno add @teever/ez-hook`
66
+ - `npx jsr add @teever/ez-hook`
67
+ - `yarn dlx jsr add @teever/ez-hook`
68
+ - `pnpm dlx jsr add @teever/ez-hook`
69
+ - `bunx jsr add @teever/ez-hook`
70
+
71
+
72
+ # Features
73
+
74
+ - Zero dependencies
75
+ - TypeScript support
76
+ - Automatic retry on rate limits and server errors
77
+ - Configurable retry behavior
78
+ - Fluent builder API
79
+ - Overloaded methods for simpler usage
80
+ - Structured responses with status/retry metadata
81
+
82
+ ## Response shape
83
+
84
+ `send`, `modify`, and `get` return a `RequestResult` object:
85
+ - `ok`: boolean success indicator
86
+ - `status`: HTTP status code (0 on network failure)
87
+ - `retryAfter`: milliseconds until retry if provided by Discord
88
+ - `bodyText`: raw response text, when present
89
+ - `error`: message for non-OK responses
90
+
91
+ Input validation errors throw `ValidationError` with the field path and limit details.
92
+
93
+ ## Request options
94
+
95
+ You can pass a second parameter with `signal`, custom `headers`, and `timeoutMs`:
96
+
97
+ ```ts
98
+ const controller = new AbortController()
99
+ const res = await hook.send({
100
+ headers: { 'X-Custom-Header': 'value' },
101
+ signal: controller.signal,
102
+ timeoutMs: 5000
103
+ })
104
+ ```
105
+
106
+ # Example
107
+
108
+
109
+ ## Basic Use
110
+
111
+ ```ts
112
+ import { Webhook } from '@teever/ez-hook'
113
+
114
+ // Optional retry configuration
115
+ const retryConfig = {
116
+ maxRetries: 3, // Maximum number of retries
117
+ baseDelay: 1000, // Base delay in ms (1 second)
118
+ maxDelay: 60000 // Maximum delay in ms (60 seconds)
119
+ } // Also the default configuration
120
+
121
+ const hook = new Webhook('https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz', retryConfig)
122
+
123
+ hook
124
+ .setUsername('Username')
125
+ .setContent('Lorem ipsum dolor sit amet, consectetur adipiscing elit.')
126
+
127
+ const result = await hook.send()
128
+
129
+ if (!result.ok) {
130
+ console.error('Webhook failed', result)
131
+ }
132
+
133
+ ```
134
+
135
+ ## Custom Embeds (Rich Message)
136
+
137
+ ```ts
138
+ import { Embed, Webhook } from '@teever/ez-hook'
139
+
140
+ const hook = new Webhook('https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz')
141
+
142
+ const embed = new Embed()
143
+ embed
144
+ .setTitle('Embed Title')
145
+ .setDescription('Embed Description')
146
+ // Use hex string or number for color
147
+ .setColor('#ffffff') // (Note: must be prefixed with #)
148
+ // Example number for color
149
+ .setColor(12345)
150
+ // Simple method overload
151
+ .setThumbnail('https://example.com/image.png')
152
+ // Or use full object
153
+ .setThumbnail({
154
+ url: 'https://example.com/image.png',
155
+ height: 100,
156
+ width: 100
157
+ })
158
+ // Simple author setting
159
+ .setAuthor('Author Name', 'https://discord.com', 'https://example.com/icon.png')
160
+ // Or use full object
161
+ .setAuthor({
162
+ name: 'Author Name',
163
+ icon_url: 'https://example.com/icon.png',
164
+ url: 'https://discord.com'
165
+ })
166
+ // Simple footer setting
167
+ .setFooter('Footer Text', 'https://example.com/icon.png')
168
+ // Or use full object
169
+ .setFooter({
170
+ text: 'Footer Text',
171
+ icon_url: 'https://example.com/icon.png'
172
+ })
173
+ .setTimestamp()
174
+ // Simple field adding
175
+ .addField('Field 1', 'Value 1', true)
176
+ // Or use full object
177
+ .addField({
178
+ name: 'Field 2',
179
+ value: 'Value 2',
180
+ inline: true
181
+ })
182
+
183
+ const res = await hook.addEmbed(embed).send()
184
+
185
+ if (!res.ok) {
186
+ console.error('Webhook failed', res)
187
+ }
188
+
189
+ ```
190
+
191
+ ## Error Handling
192
+
193
+ EZ-Hook provides typed error classes for precise error handling:
194
+
195
+ ```ts
196
+ import {
197
+ Webhook,
198
+ ValidationError,
199
+ RateLimitError,
200
+ WebhookError,
201
+ WebhookNotFoundError
202
+ } from '@teever/ez-hook'
203
+
204
+ const hook = new Webhook('https://discord.com/api/webhooks/...')
205
+
206
+ try {
207
+ hook.setContent('Hello!')
208
+ await hook.send()
209
+ } catch (error) {
210
+ if (error instanceof ValidationError) {
211
+ console.error(`Validation failed: ${error.field}`)
212
+ console.error(`Max: ${error.maxLength}, Actual: ${error.actualLength}`)
213
+ } else if (error instanceof RateLimitError) {
214
+ console.error(`Rate limited! Retry after ${error.retryAfter}ms`)
215
+ } else if (error instanceof WebhookNotFoundError) {
216
+ console.error('Webhook URL is invalid or deleted')
217
+ } else if (error instanceof WebhookError) {
218
+ console.error(`HTTP error ${error.statusCode}: ${error.message}`)
219
+ }
220
+ }
221
+ ```
222
+
223
+ ## Examples
224
+
225
+ See the [examples](./examples) directory for more usage patterns:
226
+
227
+ - [Basic usage](./examples/02-basic-usage.ts) - simple messages, overrides, TTS
228
+ - [Multiple embeds](./examples/03-multiple-embeds.ts) - dashboards, catalogs, leaderboards
229
+ - [Embed features](./examples/04-embed-features.ts) - all embed options, colors, fields
230
+ - [Webhook management](./examples/05-webhook-management.ts) - get/modify webhooks
231
+ - [Error handling](./examples/06-error-handling.ts) - comprehensive error patterns
package/package.json CHANGED
@@ -1,18 +1,24 @@
1
1
  {
2
2
  "name": "@teever/ez-hook",
3
3
  "module": "dist/index.js",
4
+ "description": "A simple way to send webhooks to discord with zero dependencies",
5
+ "author": "github.com/teeverc",
6
+ "version": "0.3.6",
7
+ "license": "MIT",
4
8
  "main": "dist/index.js",
5
9
  "types": "dist/index.d.ts",
10
+ "exports": {
11
+ ".": {
12
+ "import": "./dist/index.js",
13
+ "types": "./dist/index.d.ts"
14
+ }
15
+ },
6
16
  "type": "module",
7
17
  "files": [
8
18
  "dist",
9
19
  "README.md",
10
20
  "LICENSE"
11
21
  ],
12
- "description": "A simple way to send webhooks to discord with zero dependencies",
13
- "author": "github.com/teeverc",
14
- "version": "0.3.5",
15
- "license": "MIT",
16
22
  "repository": {
17
23
  "type": "git",
18
24
  "url": "git+https://github.com/teeverc/ez-hook.git"
@@ -33,29 +39,17 @@
33
39
  "access": "public"
34
40
  },
35
41
  "scripts": {
36
- "start": "bun src/index.ts",
37
- "dev": "bun src/index.ts",
38
- "dev:watch": "bun build --watch",
39
42
  "build": "bun run clean && tsc --project tsconfig.build.json",
40
- "build:watch": "tsc --project tsconfig.build.json --watch",
41
- "lint": "biome lint ./src",
42
- "format": "biome check --write --unsafe ./src",
43
- "check": "biome check --write ./src",
44
- "check:ci": "biome check ./src",
45
- "test": "bun test webhook",
46
- "test:watch": "bun test --watch webhook",
47
- "test:coverage": "bun test --coverage webhook",
43
+ "check": "biome check --write --unsafe ./src",
48
44
  "typecheck": "tsc --noEmit",
49
45
  "clean": "rm -rf dist build",
50
- "example": "bun examples/01-enhanced-usage.ts",
51
- "example:basic": "bun examples/basic-usage.ts",
52
- "validate": "bun run typecheck && bun run check:ci && bun run test",
53
- "prepublishOnly": "bun run validate && bun run build"
46
+ "prepublishOnly": "bun run build",
47
+ "prepare": "lefthook install"
54
48
  },
55
49
  "devDependencies": {
56
- "@biomejs/biome": "^2.2.4",
57
- "@types/bun": "^1.2.22",
58
- "lefthook": "^2.0.1",
50
+ "@biomejs/biome": "2.3.14",
51
+ "@types/bun": "^1.3.8",
52
+ "lefthook": "^2.1.0",
59
53
  "typescript": "^5.9.3"
60
54
  }
61
55
  }