@primitivedotdev/sdk 0.25.0 → 0.25.2
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.
- package/dist/api/generated/index.js +1 -1
- package/dist/api/generated/sdk.gen.js +19 -0
- package/dist/api/index.d.ts +3 -2
- package/dist/api/index.js +6 -0
- package/dist/api/verify-signature.js +198 -0
- package/dist/{api-C3X14uId.js → api-Cfj_U9RX.js} +164 -2
- package/dist/contract/index.d.ts +1 -1
- package/dist/contract/index.js +1 -1
- package/dist/errors-C53fe686.d.ts +245 -0
- package/dist/errors-x91I_yEt.js +287 -0
- package/dist/{index-jLAAV6Sq.d.ts → index-DISHEO_u.d.ts} +204 -3
- package/dist/{index-CDlwyxdp.d.ts → index-Dbx9udpX.d.ts} +2 -210
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3 -3
- package/dist/openapi/openapi.generated.js +144 -0
- package/dist/openapi/operations.generated.js +110 -0
- package/dist/webhook/errors.js +224 -0
- package/dist/webhook/index.d.ts +2 -2
- package/dist/webhook/index.js +2 -2
- package/dist/{webhook-rUjGV6Zu.js → webhook-DJkfUnFZ.js} +2 -220
- package/oclif.manifest.json +73 -1
- package/package.json +1 -1
- package/dist/received-email-D6tKtWwW.js +0 -69
- package/dist/received-email-DNjpq_Wt.d.ts +0 -37
|
@@ -2891,6 +2891,99 @@ export const openapiDocument = {
|
|
|
2891
2891
|
}
|
|
2892
2892
|
}
|
|
2893
2893
|
}
|
|
2894
|
+
},
|
|
2895
|
+
"/functions/{id}/logs": {
|
|
2896
|
+
"parameters": [
|
|
2897
|
+
{
|
|
2898
|
+
"$ref": "#/components/parameters/ResourceId"
|
|
2899
|
+
}
|
|
2900
|
+
],
|
|
2901
|
+
"get": {
|
|
2902
|
+
"operationId": "listFunctionLogs",
|
|
2903
|
+
"summary": "List a function's execution logs",
|
|
2904
|
+
"description": "Returns the most recent `function_logs` rows for the function,\nnewest first. Each row is a single `console.log` / `console.error`\ninvocation captured from the running handler.\n\nPage through history with the opaque `cursor` returned as\n`next_cursor`; pass it back as the `cursor` query param on the\nnext call. `next_cursor` is `null` when there are no further\nrows. The cursor format is an implementation detail and should\nnot be parsed by callers.\n",
|
|
2905
|
+
"tags": [
|
|
2906
|
+
"Functions"
|
|
2907
|
+
],
|
|
2908
|
+
"parameters": [
|
|
2909
|
+
{
|
|
2910
|
+
"name": "limit",
|
|
2911
|
+
"in": "query",
|
|
2912
|
+
"required": false,
|
|
2913
|
+
"description": "Maximum number of rows to return. Clamped to 1..200; default\n50.\n",
|
|
2914
|
+
"schema": {
|
|
2915
|
+
"type": "integer",
|
|
2916
|
+
"minimum": 1,
|
|
2917
|
+
"maximum": 200,
|
|
2918
|
+
"default": 50
|
|
2919
|
+
}
|
|
2920
|
+
},
|
|
2921
|
+
{
|
|
2922
|
+
"name": "cursor",
|
|
2923
|
+
"in": "query",
|
|
2924
|
+
"required": false,
|
|
2925
|
+
"description": "Opaque pagination cursor from a previous response's\n`next_cursor`. Omit on the first call.\n",
|
|
2926
|
+
"schema": {
|
|
2927
|
+
"type": "string"
|
|
2928
|
+
}
|
|
2929
|
+
}
|
|
2930
|
+
],
|
|
2931
|
+
"responses": {
|
|
2932
|
+
"200": {
|
|
2933
|
+
"description": "List of log rows (newest first) plus pagination cursor.",
|
|
2934
|
+
"content": {
|
|
2935
|
+
"application/json": {
|
|
2936
|
+
"schema": {
|
|
2937
|
+
"allOf": [
|
|
2938
|
+
{
|
|
2939
|
+
"$ref": "#/components/schemas/SuccessEnvelope"
|
|
2940
|
+
},
|
|
2941
|
+
{
|
|
2942
|
+
"type": "object",
|
|
2943
|
+
"properties": {
|
|
2944
|
+
"data": {
|
|
2945
|
+
"type": "object",
|
|
2946
|
+
"properties": {
|
|
2947
|
+
"items": {
|
|
2948
|
+
"type": "array",
|
|
2949
|
+
"items": {
|
|
2950
|
+
"$ref": "#/components/schemas/FunctionLogRow"
|
|
2951
|
+
}
|
|
2952
|
+
},
|
|
2953
|
+
"next_cursor": {
|
|
2954
|
+
"type": [
|
|
2955
|
+
"string",
|
|
2956
|
+
"null"
|
|
2957
|
+
],
|
|
2958
|
+
"description": "Pass back as `cursor` to fetch the next\npage. `null` when no further rows exist.\n"
|
|
2959
|
+
}
|
|
2960
|
+
},
|
|
2961
|
+
"required": [
|
|
2962
|
+
"items",
|
|
2963
|
+
"next_cursor"
|
|
2964
|
+
]
|
|
2965
|
+
}
|
|
2966
|
+
}
|
|
2967
|
+
}
|
|
2968
|
+
]
|
|
2969
|
+
}
|
|
2970
|
+
}
|
|
2971
|
+
}
|
|
2972
|
+
},
|
|
2973
|
+
"400": {
|
|
2974
|
+
"$ref": "#/components/responses/ValidationError"
|
|
2975
|
+
},
|
|
2976
|
+
"401": {
|
|
2977
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
2978
|
+
},
|
|
2979
|
+
"403": {
|
|
2980
|
+
"$ref": "#/components/responses/Forbidden"
|
|
2981
|
+
},
|
|
2982
|
+
"404": {
|
|
2983
|
+
"$ref": "#/components/responses/NotFound"
|
|
2984
|
+
}
|
|
2985
|
+
}
|
|
2986
|
+
}
|
|
2894
2987
|
}
|
|
2895
2988
|
},
|
|
2896
2989
|
"components": {
|
|
@@ -5501,6 +5594,57 @@ export const openapiDocument = {
|
|
|
5501
5594
|
"watch_url"
|
|
5502
5595
|
]
|
|
5503
5596
|
},
|
|
5597
|
+
"FunctionLogRow": {
|
|
5598
|
+
"type": "object",
|
|
5599
|
+
"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
|
|
5600
|
+
"properties": {
|
|
5601
|
+
"id": {
|
|
5602
|
+
"type": "string",
|
|
5603
|
+
"format": "uuid",
|
|
5604
|
+
"description": "Unique log row id (stable across pages)."
|
|
5605
|
+
},
|
|
5606
|
+
"function_id": {
|
|
5607
|
+
"type": "string",
|
|
5608
|
+
"format": "uuid",
|
|
5609
|
+
"description": "The function this log row belongs to."
|
|
5610
|
+
},
|
|
5611
|
+
"level": {
|
|
5612
|
+
"type": "string",
|
|
5613
|
+
"enum": [
|
|
5614
|
+
"debug",
|
|
5615
|
+
"log",
|
|
5616
|
+
"info",
|
|
5617
|
+
"warn",
|
|
5618
|
+
"error"
|
|
5619
|
+
],
|
|
5620
|
+
"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
|
|
5621
|
+
},
|
|
5622
|
+
"message": {
|
|
5623
|
+
"type": "string",
|
|
5624
|
+
"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
|
|
5625
|
+
},
|
|
5626
|
+
"ts": {
|
|
5627
|
+
"type": "string",
|
|
5628
|
+
"format": "date-time",
|
|
5629
|
+
"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
|
|
5630
|
+
},
|
|
5631
|
+
"metadata": {
|
|
5632
|
+
"type": [
|
|
5633
|
+
"object",
|
|
5634
|
+
"null"
|
|
5635
|
+
],
|
|
5636
|
+
"additionalProperties": true,
|
|
5637
|
+
"description": "Optional structured payload the runtime attaches alongside\nthe message (e.g. extra args passed to `console.log`).\nShape is opaque; treat keys as untyped.\n"
|
|
5638
|
+
}
|
|
5639
|
+
},
|
|
5640
|
+
"required": [
|
|
5641
|
+
"id",
|
|
5642
|
+
"function_id",
|
|
5643
|
+
"level",
|
|
5644
|
+
"message",
|
|
5645
|
+
"ts"
|
|
5646
|
+
]
|
|
5647
|
+
},
|
|
5504
5648
|
"FunctionSecretListItem": {
|
|
5505
5649
|
"type": "object",
|
|
5506
5650
|
"description": "One row from GET /functions/{id}/secrets. Discriminate on the\n`managed` field:\n * `managed = true` — system secret provisioned by Primitive.\n `description` is set; `created_at` / `updated_at` are\n null because the row is virtual (resolved at deploy time\n from the managed registry, not stored in the secrets\n table).\n * `managed = false` — secret the user set via the API.\n `created_at` / `updated_at` are set; `description` is\n null.\n",
|
|
@@ -2808,6 +2808,116 @@ export const operationManifest = [
|
|
|
2808
2808
|
"tag": "Functions",
|
|
2809
2809
|
"tagCommand": "functions"
|
|
2810
2810
|
},
|
|
2811
|
+
{
|
|
2812
|
+
"binaryResponse": false,
|
|
2813
|
+
"bodyRequired": false,
|
|
2814
|
+
"command": "list-function-logs",
|
|
2815
|
+
"description": "Returns the most recent `function_logs` rows for the function,\nnewest first. Each row is a single `console.log` / `console.error`\ninvocation captured from the running handler.\n\nPage through history with the opaque `cursor` returned as\n`next_cursor`; pass it back as the `cursor` query param on the\nnext call. `next_cursor` is `null` when there are no further\nrows. The cursor format is an implementation detail and should\nnot be parsed by callers.\n",
|
|
2816
|
+
"hasJsonBody": false,
|
|
2817
|
+
"method": "GET",
|
|
2818
|
+
"operationId": "listFunctionLogs",
|
|
2819
|
+
"path": "/functions/{id}/logs",
|
|
2820
|
+
"pathParams": [
|
|
2821
|
+
{
|
|
2822
|
+
"description": "Resource UUID",
|
|
2823
|
+
"enum": null,
|
|
2824
|
+
"name": "id",
|
|
2825
|
+
"required": true,
|
|
2826
|
+
"type": "string"
|
|
2827
|
+
}
|
|
2828
|
+
],
|
|
2829
|
+
"queryParams": [
|
|
2830
|
+
{
|
|
2831
|
+
"description": "Maximum number of rows to return. Clamped to 1..200; default\n50.\n",
|
|
2832
|
+
"enum": null,
|
|
2833
|
+
"name": "limit",
|
|
2834
|
+
"required": false,
|
|
2835
|
+
"type": "integer"
|
|
2836
|
+
},
|
|
2837
|
+
{
|
|
2838
|
+
"description": "Opaque pagination cursor from a previous response's\n`next_cursor`. Omit on the first call.\n",
|
|
2839
|
+
"enum": null,
|
|
2840
|
+
"name": "cursor",
|
|
2841
|
+
"required": false,
|
|
2842
|
+
"type": "string"
|
|
2843
|
+
}
|
|
2844
|
+
],
|
|
2845
|
+
"requestSchema": null,
|
|
2846
|
+
"responseSchema": {
|
|
2847
|
+
"type": "object",
|
|
2848
|
+
"properties": {
|
|
2849
|
+
"items": {
|
|
2850
|
+
"type": "array",
|
|
2851
|
+
"items": {
|
|
2852
|
+
"type": "object",
|
|
2853
|
+
"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
|
|
2854
|
+
"properties": {
|
|
2855
|
+
"id": {
|
|
2856
|
+
"type": "string",
|
|
2857
|
+
"format": "uuid",
|
|
2858
|
+
"description": "Unique log row id (stable across pages)."
|
|
2859
|
+
},
|
|
2860
|
+
"function_id": {
|
|
2861
|
+
"type": "string",
|
|
2862
|
+
"format": "uuid",
|
|
2863
|
+
"description": "The function this log row belongs to."
|
|
2864
|
+
},
|
|
2865
|
+
"level": {
|
|
2866
|
+
"type": "string",
|
|
2867
|
+
"enum": [
|
|
2868
|
+
"debug",
|
|
2869
|
+
"log",
|
|
2870
|
+
"info",
|
|
2871
|
+
"warn",
|
|
2872
|
+
"error"
|
|
2873
|
+
],
|
|
2874
|
+
"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
|
|
2875
|
+
},
|
|
2876
|
+
"message": {
|
|
2877
|
+
"type": "string",
|
|
2878
|
+
"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
|
|
2879
|
+
},
|
|
2880
|
+
"ts": {
|
|
2881
|
+
"type": "string",
|
|
2882
|
+
"format": "date-time",
|
|
2883
|
+
"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
|
|
2884
|
+
},
|
|
2885
|
+
"metadata": {
|
|
2886
|
+
"type": [
|
|
2887
|
+
"object",
|
|
2888
|
+
"null"
|
|
2889
|
+
],
|
|
2890
|
+
"additionalProperties": true,
|
|
2891
|
+
"description": "Optional structured payload the runtime attaches alongside\nthe message (e.g. extra args passed to `console.log`).\nShape is opaque; treat keys as untyped.\n"
|
|
2892
|
+
}
|
|
2893
|
+
},
|
|
2894
|
+
"required": [
|
|
2895
|
+
"id",
|
|
2896
|
+
"function_id",
|
|
2897
|
+
"level",
|
|
2898
|
+
"message",
|
|
2899
|
+
"ts"
|
|
2900
|
+
]
|
|
2901
|
+
}
|
|
2902
|
+
},
|
|
2903
|
+
"next_cursor": {
|
|
2904
|
+
"type": [
|
|
2905
|
+
"string",
|
|
2906
|
+
"null"
|
|
2907
|
+
],
|
|
2908
|
+
"description": "Pass back as `cursor` to fetch the next\npage. `null` when no further rows exist.\n"
|
|
2909
|
+
}
|
|
2910
|
+
},
|
|
2911
|
+
"required": [
|
|
2912
|
+
"items",
|
|
2913
|
+
"next_cursor"
|
|
2914
|
+
]
|
|
2915
|
+
},
|
|
2916
|
+
"sdkName": "listFunctionLogs",
|
|
2917
|
+
"summary": "List a function's execution logs",
|
|
2918
|
+
"tag": "Functions",
|
|
2919
|
+
"tagCommand": "functions"
|
|
2920
|
+
},
|
|
2811
2921
|
{
|
|
2812
2922
|
"binaryResponse": false,
|
|
2813
2923
|
"bodyRequired": false,
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
// -----------------------------------------------------------------------------
|
|
2
|
+
// Error Definitions (Single Source of Truth)
|
|
3
|
+
// -----------------------------------------------------------------------------
|
|
4
|
+
/**
|
|
5
|
+
* Verification error definitions.
|
|
6
|
+
* Use these for documentation, dashboards, and i18n.
|
|
7
|
+
*/
|
|
8
|
+
export const VERIFICATION_ERRORS = {
|
|
9
|
+
INVALID_SIGNATURE_HEADER: {
|
|
10
|
+
message: "Missing or malformed Primitive-Signature header",
|
|
11
|
+
suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework.",
|
|
12
|
+
},
|
|
13
|
+
TIMESTAMP_OUT_OF_RANGE: {
|
|
14
|
+
message: "Timestamp is too old (possible replay attack)",
|
|
15
|
+
suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced.",
|
|
16
|
+
},
|
|
17
|
+
SIGNATURE_MISMATCH: {
|
|
18
|
+
message: "Signature doesn't match expected value",
|
|
19
|
+
suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).",
|
|
20
|
+
},
|
|
21
|
+
MISSING_SECRET: {
|
|
22
|
+
message: "No webhook secret was provided",
|
|
23
|
+
suggestion: "Pass your webhook secret from the Primitive dashboard. Check that the environment variable is set.",
|
|
24
|
+
},
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Payload parsing error definitions.
|
|
28
|
+
* Use these for documentation, dashboards, and i18n.
|
|
29
|
+
*/
|
|
30
|
+
export const PAYLOAD_ERRORS = {
|
|
31
|
+
PAYLOAD_NULL: {
|
|
32
|
+
message: "Webhook payload is null",
|
|
33
|
+
suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware.",
|
|
34
|
+
},
|
|
35
|
+
PAYLOAD_UNDEFINED: {
|
|
36
|
+
message: "Webhook payload is undefined",
|
|
37
|
+
suggestion: "The payload was not provided. Make sure you're passing the request body to the handler.",
|
|
38
|
+
},
|
|
39
|
+
PAYLOAD_WRONG_TYPE: {
|
|
40
|
+
message: "Webhook payload must be an object",
|
|
41
|
+
suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive.",
|
|
42
|
+
},
|
|
43
|
+
PAYLOAD_IS_ARRAY: {
|
|
44
|
+
message: "Webhook payload is an array, expected object",
|
|
45
|
+
suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure.",
|
|
46
|
+
},
|
|
47
|
+
PAYLOAD_MISSING_EVENT: {
|
|
48
|
+
message: "Webhook payload missing 'event' field",
|
|
49
|
+
suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook.",
|
|
50
|
+
},
|
|
51
|
+
PAYLOAD_UNKNOWN_EVENT: {
|
|
52
|
+
message: "Unknown webhook event type",
|
|
53
|
+
suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully.",
|
|
54
|
+
},
|
|
55
|
+
PAYLOAD_EMPTY_BODY: {
|
|
56
|
+
message: "Request body is empty",
|
|
57
|
+
suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly.",
|
|
58
|
+
},
|
|
59
|
+
JSON_PARSE_FAILED: {
|
|
60
|
+
message: "Failed to parse JSON body",
|
|
61
|
+
suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header.",
|
|
62
|
+
},
|
|
63
|
+
INVALID_ENCODING: {
|
|
64
|
+
message: "Invalid body encoding",
|
|
65
|
+
suggestion: "The request body encoding is not supported. Primitive webhooks use UTF-8 encoded JSON.",
|
|
66
|
+
},
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* Raw email decode error definitions.
|
|
70
|
+
* Use these for documentation, dashboards, and i18n.
|
|
71
|
+
*/
|
|
72
|
+
export const RAW_EMAIL_ERRORS = {
|
|
73
|
+
NOT_INCLUDED: {
|
|
74
|
+
message: "Raw email content not included inline",
|
|
75
|
+
suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email.",
|
|
76
|
+
},
|
|
77
|
+
INVALID_BASE64: {
|
|
78
|
+
message: "Raw email content is not valid base64",
|
|
79
|
+
suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload.",
|
|
80
|
+
},
|
|
81
|
+
HASH_MISMATCH: {
|
|
82
|
+
message: "SHA-256 hash verification failed",
|
|
83
|
+
suggestion: "The raw email data may be corrupted. Try downloading from the URL instead.",
|
|
84
|
+
},
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* Base class for all Primitive webhook errors.
|
|
88
|
+
*
|
|
89
|
+
* Catch this to handle any error from the SDK in a single catch block.
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ```typescript
|
|
93
|
+
* import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
|
|
94
|
+
*
|
|
95
|
+
* try {
|
|
96
|
+
* const event = handleWebhook({ body, headers, secret });
|
|
97
|
+
* } catch (err) {
|
|
98
|
+
* if (err instanceof PrimitiveWebhookError) {
|
|
99
|
+
* console.error(`[${err.code}] ${err.message}`);
|
|
100
|
+
* return res.status(400).json({ error: err.code });
|
|
101
|
+
* }
|
|
102
|
+
* throw err;
|
|
103
|
+
* }
|
|
104
|
+
* ```
|
|
105
|
+
*/
|
|
106
|
+
export class PrimitiveWebhookError extends Error {
|
|
107
|
+
/**
|
|
108
|
+
* Formats the error for logging/display.
|
|
109
|
+
*/
|
|
110
|
+
toString() {
|
|
111
|
+
return `${this.name} [${this.code}]: ${this.message}\n\nSuggestion: ${this.suggestion}`;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
|
|
115
|
+
*/
|
|
116
|
+
toJSON() {
|
|
117
|
+
return {
|
|
118
|
+
name: this.name,
|
|
119
|
+
code: this.code,
|
|
120
|
+
message: this.message,
|
|
121
|
+
suggestion: this.suggestion,
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Error thrown when webhook signature verification fails.
|
|
127
|
+
*
|
|
128
|
+
* Use the `code` property to programmatically handle specific error cases.
|
|
129
|
+
*/
|
|
130
|
+
export class WebhookVerificationError extends PrimitiveWebhookError {
|
|
131
|
+
code;
|
|
132
|
+
suggestion;
|
|
133
|
+
constructor(code, message, suggestion) {
|
|
134
|
+
super(message ?? VERIFICATION_ERRORS[code].message);
|
|
135
|
+
this.name = "WebhookVerificationError";
|
|
136
|
+
this.code = code;
|
|
137
|
+
this.suggestion = suggestion ?? VERIFICATION_ERRORS[code].suggestion;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Error thrown when webhook payload parsing fails (lightweight parser).
|
|
142
|
+
*
|
|
143
|
+
* Use the `code` property for programmatic handling and monitoring.
|
|
144
|
+
* The `suggestion` property contains actionable guidance for fixing the issue.
|
|
145
|
+
*/
|
|
146
|
+
export class WebhookPayloadError extends PrimitiveWebhookError {
|
|
147
|
+
code;
|
|
148
|
+
suggestion;
|
|
149
|
+
/** Original error if this wraps another error (e.g., JSON.parse failure) */
|
|
150
|
+
cause;
|
|
151
|
+
constructor(code, message, suggestion, cause) {
|
|
152
|
+
super(message ?? PAYLOAD_ERRORS[code].message);
|
|
153
|
+
this.name = "WebhookPayloadError";
|
|
154
|
+
this.code = code;
|
|
155
|
+
this.suggestion = suggestion ?? PAYLOAD_ERRORS[code].suggestion;
|
|
156
|
+
this.cause = cause;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Error thrown when schema validation fails.
|
|
161
|
+
*/
|
|
162
|
+
export class WebhookValidationError extends PrimitiveWebhookError {
|
|
163
|
+
code = "SCHEMA_VALIDATION_FAILED";
|
|
164
|
+
suggestion;
|
|
165
|
+
/** The specific field path that failed (e.g., "email.headers.from") */
|
|
166
|
+
field;
|
|
167
|
+
/** Original schema validation errors for advanced debugging */
|
|
168
|
+
validationErrors;
|
|
169
|
+
/** Number of additional validation errors beyond the first */
|
|
170
|
+
additionalErrorCount;
|
|
171
|
+
constructor(field, message, suggestion, validationErrors) {
|
|
172
|
+
super(message);
|
|
173
|
+
this.name = "WebhookValidationError";
|
|
174
|
+
this.field = field;
|
|
175
|
+
this.suggestion = suggestion;
|
|
176
|
+
this.validationErrors = validationErrors;
|
|
177
|
+
this.additionalErrorCount = Math.max(0, validationErrors.length - 1);
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Formats the error for logging/display.
|
|
181
|
+
* Includes error count and suggestion.
|
|
182
|
+
*/
|
|
183
|
+
toString() {
|
|
184
|
+
let output = `${this.name} [${this.code}]: ${this.message}`;
|
|
185
|
+
if (this.additionalErrorCount > 0) {
|
|
186
|
+
output += ` (and ${this.additionalErrorCount} more validation error${this.additionalErrorCount > 1 ? "s" : ""})`;
|
|
187
|
+
}
|
|
188
|
+
output += `\n\nSuggestion: ${this.suggestion}`;
|
|
189
|
+
return output;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
|
|
193
|
+
*/
|
|
194
|
+
toJSON() {
|
|
195
|
+
return {
|
|
196
|
+
name: this.name,
|
|
197
|
+
code: this.code,
|
|
198
|
+
field: this.field,
|
|
199
|
+
message: this.message,
|
|
200
|
+
suggestion: this.suggestion,
|
|
201
|
+
additionalErrorCount: this.additionalErrorCount,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
// -----------------------------------------------------------------------------
|
|
206
|
+
// Raw Email Decode Errors
|
|
207
|
+
// -----------------------------------------------------------------------------
|
|
208
|
+
/**
|
|
209
|
+
* Error thrown when raw email decoding or verification fails.
|
|
210
|
+
*
|
|
211
|
+
* Use the `code` property to determine the failure reason:
|
|
212
|
+
* - `NOT_INCLUDED`: Raw email not inline, must download from URL
|
|
213
|
+
* - `HASH_MISMATCH`: SHA-256 verification failed, content may be corrupted
|
|
214
|
+
*/
|
|
215
|
+
export class RawEmailDecodeError extends PrimitiveWebhookError {
|
|
216
|
+
code;
|
|
217
|
+
suggestion;
|
|
218
|
+
constructor(code, message) {
|
|
219
|
+
super(message ?? RAW_EMAIL_ERRORS[code].message);
|
|
220
|
+
this.name = "RawEmailDecodeError";
|
|
221
|
+
this.code = code;
|
|
222
|
+
this.suggestion = RAW_EMAIL_ERRORS[code].suggestion;
|
|
223
|
+
}
|
|
224
|
+
}
|
package/dist/webhook/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "../types-9vXGZjPd.js";
|
|
2
|
-
import { a as
|
|
3
|
-
import { A as VerifyOptions,
|
|
2
|
+
import { _ as buildForwardSubject, a as RawEmailDecodeErrorCode, b as normalizeReceivedEmail, c as WebhookPayloadError, d as WebhookValidationErrorCode, f as WebhookVerificationError, g as ReceivedEmailThread, h as ReceivedEmailAddress, i as RawEmailDecodeError, l as WebhookPayloadErrorCode, m as ReceivedEmail, n as PrimitiveWebhookError, o as VERIFICATION_ERRORS, p as WebhookVerificationErrorCode, r as RAW_EMAIL_ERRORS, s as WebhookErrorCode, t as PAYLOAD_ERRORS, u as WebhookValidationError, v as buildReplySubject, x as parseHeaderAddress, y as formatAddress } from "../errors-C53fe686.js";
|
|
3
|
+
import { A as VerifyOptions, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, I as generateDownloadToken, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "../index-Dbx9udpX.js";
|
|
4
4
|
export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, ReceiveRequestOptions, ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, buildForwardSubject, buildReplySubject, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
|
package/dist/webhook/index.js
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
import { a as
|
|
2
|
-
import { A as PRIMITIVE_CONFIRMED_HEADER,
|
|
1
|
+
import { a as VERIFICATION_ERRORS, c as WebhookVerificationError, d as formatAddress, f as normalizeReceivedEmail, i as RawEmailDecodeError, l as buildForwardSubject, n as PrimitiveWebhookError, o as WebhookPayloadError, p as parseHeaderAddress, r as RAW_EMAIL_ERRORS, s as WebhookValidationError, t as PAYLOAD_ERRORS, u as buildReplySubject } from "../errors-x91I_yEt.js";
|
|
2
|
+
import { A as PRIMITIVE_CONFIRMED_HEADER, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict } from "../webhook-DJkfUnFZ.js";
|
|
3
3
|
export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, buildForwardSubject, buildReplySubject, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
|