@atlasauth/backend 0.11.0 → 0.13.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.
- package/CHANGELOG.md +17 -0
- package/README.md +22 -0
- package/dist/client/index.d.ts +17 -0
- package/dist/client/index.js +4 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/referrals.d.ts +234 -6
- package/dist/client/referrals.js +31 -0
- package/dist/client/referrals.js.map +1 -1
- package/dist/client/user-hooks.d.ts +58 -0
- package/dist/client/user-hooks.js +21 -0
- package/dist/client/user-hooks.js.map +1 -0
- package/dist/client/users.d.ts +63 -1
- package/dist/client/users.js +9 -0
- package/dist/client/users.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +8 -1
- package/dist/index.js.map +1 -1
- package/dist/referral-test-calls.d.ts +106 -0
- package/dist/referral-test-calls.js +102 -0
- package/dist/referral-test-calls.js.map +1 -0
- package/dist/referrals.d.ts +66 -6
- package/dist/referrals.js +17 -4
- package/dist/referrals.js.map +1 -1
- package/dist/testing.d.ts +17 -0
- package/dist/testing.js +4 -0
- package/dist/testing.js.map +1 -1
- package/package.json +1 -1
package/dist/client/users.d.ts
CHANGED
|
@@ -44,8 +44,19 @@ export interface UserReferral {
|
|
|
44
44
|
referrer_user_id: string | null;
|
|
45
45
|
/** How the platform matched the referral, e.g. `code`, `click`, `coupon`. */
|
|
46
46
|
matched_via: string | null;
|
|
47
|
-
/**
|
|
47
|
+
/**
|
|
48
|
+
* The attribution status: `pending` (the platform has not answered yet),
|
|
49
|
+
* `attributed`, `none`, `failed`, `held` or `flagged`. Servers before
|
|
50
|
+
* referral attribution v2 sent the platform's own status here; that is now
|
|
51
|
+
* `referral_status`.
|
|
52
|
+
*/
|
|
48
53
|
status: string | null;
|
|
54
|
+
/** The referrer as the platform knows them. Same value as `referrer_external_id`. */
|
|
55
|
+
partner_external_ref?: string | null;
|
|
56
|
+
/** The platform's own status for the referral, e.g. `active`. */
|
|
57
|
+
referral_status?: string | null;
|
|
58
|
+
/** The platform's reasoning notes (why it matched, or why not). */
|
|
59
|
+
notes?: string[] | null;
|
|
49
60
|
/** The risk level Atlas assessed at sign-up, when one was. */
|
|
50
61
|
risk_level?: 'low' | 'medium' | 'high' | null;
|
|
51
62
|
/** An admin marked the referral fraudulent (`users.flagReferral`). */
|
|
@@ -89,6 +100,44 @@ export interface UserReferralAttributedEvent {
|
|
|
89
100
|
signed_up_at: number;
|
|
90
101
|
updated_at: number;
|
|
91
102
|
}
|
|
103
|
+
/**
|
|
104
|
+
* The `data` of a `user.referral_resolved` webhook: a referral call that was
|
|
105
|
+
* still pending when `user.created` was sent has a final result (attributed,
|
|
106
|
+
* none or failed). `user.referral_attributed` still fires too when attributed.
|
|
107
|
+
*/
|
|
108
|
+
export type UserReferralResolvedEvent = UserReferralAttributedEvent;
|
|
109
|
+
/**
|
|
110
|
+
* `GET /v1/users/:id/referral`: the stored result of the user's referral
|
|
111
|
+
* calls, with no call to the platform. 404 when the user was never reported.
|
|
112
|
+
*/
|
|
113
|
+
export interface UserReferralResult {
|
|
114
|
+
object: 'user_referral';
|
|
115
|
+
user_id: string;
|
|
116
|
+
/** `pending`, `attributed`, `none`, `failed`, `held` or `flagged`. */
|
|
117
|
+
status: 'pending' | 'attributed' | 'none' | 'failed' | 'held' | 'flagged';
|
|
118
|
+
/** The id Atlas reports the user under: their `external_id`, else the Atlas user id. */
|
|
119
|
+
customer_ref: string;
|
|
120
|
+
partner_id: string | null;
|
|
121
|
+
/** The referrer as the platform knows them. */
|
|
122
|
+
partner_external_ref: string | null;
|
|
123
|
+
referrer_user_id: string | null;
|
|
124
|
+
matched_via: string | null;
|
|
125
|
+
/** The platform's own status for the referral. */
|
|
126
|
+
referral_status: string | null;
|
|
127
|
+
/** The platform's reasoning notes. */
|
|
128
|
+
notes: string[];
|
|
129
|
+
referral_code: string | null;
|
|
130
|
+
referral_link: string | null;
|
|
131
|
+
/** The referral captured at sign-up, as sent (camelCase). */
|
|
132
|
+
context: Record<string, unknown> | null;
|
|
133
|
+
risk_level: 'low' | 'medium' | 'high' | null;
|
|
134
|
+
flagged: boolean;
|
|
135
|
+
/** Why the call is held, while `held`. */
|
|
136
|
+
hold_reason: string | null;
|
|
137
|
+
/** Epoch ms. */
|
|
138
|
+
signed_up_at: number;
|
|
139
|
+
updated_at: number;
|
|
140
|
+
}
|
|
92
141
|
export interface EmailAddress {
|
|
93
142
|
object: 'email_address';
|
|
94
143
|
id: string;
|
|
@@ -152,6 +201,12 @@ export interface CreateUserBody {
|
|
|
152
201
|
export interface UpdateUserBody {
|
|
153
202
|
first_name?: string;
|
|
154
203
|
last_name?: string;
|
|
204
|
+
/**
|
|
205
|
+
* Your own id for the user; `null` clears. With referral attribution on, a
|
|
206
|
+
* change after sign-up is forwarded to the referral platform as an alias,
|
|
207
|
+
* so events under the new id still match.
|
|
208
|
+
*/
|
|
209
|
+
external_id?: string | null;
|
|
155
210
|
public_metadata?: Metadata;
|
|
156
211
|
private_metadata?: Metadata;
|
|
157
212
|
/** The user's own referral code; `null` clears. Unique per instance (`409 REFERRAL_CODE_TAKEN`). */
|
|
@@ -168,6 +223,13 @@ export declare function usersResource(request: RequestFn): {
|
|
|
168
223
|
get(id: string): Promise<User>;
|
|
169
224
|
create(body: CreateUserBody, idempotencyKey?: string): Promise<User>;
|
|
170
225
|
update(id: string, body: UpdateUserBody): Promise<User>;
|
|
226
|
+
/**
|
|
227
|
+
* Set (or clear with `null`) the user's `external_id`: `PATCH
|
|
228
|
+
* /v1/users/:id`. With referral attribution on, Atlas forwards the change
|
|
229
|
+
* to the referral platform as an alias (old id, or the Atlas user id, to
|
|
230
|
+
* the new one), so billing events under your id earn the referrer.
|
|
231
|
+
*/
|
|
232
|
+
setExternalId(id: string, externalId: string | null): Promise<User>;
|
|
171
233
|
/** `PUT /v1/users/:id/metadata` — replaces the named bags wholesale. */
|
|
172
234
|
replaceMetadata(id: string, body: ReplaceUserMetadataBody): Promise<User>;
|
|
173
235
|
ban(id: string): Promise<User>;
|
package/dist/client/users.js
CHANGED
|
@@ -17,6 +17,15 @@ function usersResource(request) {
|
|
|
17
17
|
update(id, body) {
|
|
18
18
|
return request({ method: 'PATCH', path: `/v1/users/${(0, request_1.enc)(id)}`, body });
|
|
19
19
|
},
|
|
20
|
+
/**
|
|
21
|
+
* Set (or clear with `null`) the user's `external_id`: `PATCH
|
|
22
|
+
* /v1/users/:id`. With referral attribution on, Atlas forwards the change
|
|
23
|
+
* to the referral platform as an alias (old id, or the Atlas user id, to
|
|
24
|
+
* the new one), so billing events under your id earn the referrer.
|
|
25
|
+
*/
|
|
26
|
+
setExternalId(id, externalId) {
|
|
27
|
+
return request({ method: 'PATCH', path: `/v1/users/${(0, request_1.enc)(id)}`, body: { external_id: externalId } });
|
|
28
|
+
},
|
|
20
29
|
/** `PUT /v1/users/:id/metadata` — replaces the named bags wholesale. */
|
|
21
30
|
replaceMetadata(id, body) {
|
|
22
31
|
return request({ method: 'PUT', path: `/v1/users/${(0, request_1.enc)(id)}/metadata`, body });
|
package/dist/client/users.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"users.js","sourceRoot":"","sources":["../../src/client/users.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"version":3,"file":"users.js","sourceRoot":"","sources":["../../src/client/users.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -13,6 +13,8 @@ export type { AtlasClient } from './client';
|
|
|
13
13
|
export * from './client';
|
|
14
14
|
export { createTestIssuer, TEST_TOKEN_TAMPERS } from './testing';
|
|
15
15
|
export type { TestIssuer, CreateTestIssuerOptions, MintIdTokenOptions, TestAuthorizeOptions, TestAuthorizeResult, TestTokenTamper, } from './testing';
|
|
16
|
+
export { signAtlasReferralCall, signReferallyCall, signReferralUpdatedEvent, referallySignature, referralEmailHash, REFERALLY_API_VERSION, } from './referral-test-calls';
|
|
17
|
+
export type { AtlasReferralCallOptions, ReferallyCallOptions, ReferallyCallOp, ReferralUpdatedEvent, ReferralUpdatedEventOptions, SignedReferralCall, } from './referral-test-calls';
|
|
16
18
|
export { verifyPCActn } from './pca/verify';
|
|
17
19
|
export type { PcaVerdict, PcaContext, VerifyPCActnOptions } from './pca/verify';
|
|
18
20
|
export { requirePCA, defaultExtract, memoryPcaStore } from './pca/require-pca';
|
package/dist/index.js
CHANGED
|
@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
|
14
14
|
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
15
|
};
|
|
16
16
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
-
exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = exports.verifyPCActn = exports.TEST_TOKEN_TAMPERS = exports.createTestIssuer = exports.createAtlasClient = exports.resetOidcCaches = exports.oidcVerifyIdToken = exports.oidcStart = exports.oidcLogoutUrl = exports.oidcClearCookie = exports.oidcCallback = exports.oidc = exports.OIDC_FLOW_MAX_AGE_SECONDS = exports.OIDC_FLOW_COOKIE = exports.AtlasOidcError = exports.verifyLogoutToken = exports.memoryLogoutReplayStore = exports.LogoutTokenVerifier = exports.LOGOUT_TOKEN_MAX_AGE_SECONDS = exports.LOGOUT_TOKEN_CLOCK_SKEW_SECONDS = exports.BACKCHANNEL_LOGOUT_EVENT = exports.instanceIdFromPublishableKey = exports.discoveryUrlFor = exports.JwksDiscovery = exports.DiscoveryError = void 0;
|
|
17
|
+
exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = exports.verifyPCActn = exports.REFERALLY_API_VERSION = exports.referralEmailHash = exports.referallySignature = exports.signReferralUpdatedEvent = exports.signReferallyCall = exports.signAtlasReferralCall = exports.TEST_TOKEN_TAMPERS = exports.createTestIssuer = exports.createAtlasClient = exports.resetOidcCaches = exports.oidcVerifyIdToken = exports.oidcStart = exports.oidcLogoutUrl = exports.oidcClearCookie = exports.oidcCallback = exports.oidc = exports.OIDC_FLOW_MAX_AGE_SECONDS = exports.OIDC_FLOW_COOKIE = exports.AtlasOidcError = exports.verifyLogoutToken = exports.memoryLogoutReplayStore = exports.LogoutTokenVerifier = exports.LOGOUT_TOKEN_MAX_AGE_SECONDS = exports.LOGOUT_TOKEN_CLOCK_SKEW_SECONDS = exports.BACKCHANNEL_LOGOUT_EVENT = exports.instanceIdFromPublishableKey = exports.discoveryUrlFor = exports.JwksDiscovery = exports.DiscoveryError = void 0;
|
|
18
18
|
// §7.3 token verification — the original surface, unchanged.
|
|
19
19
|
__exportStar(require("./jwks-cache"), exports);
|
|
20
20
|
// OIDC discovery of the JWKS URL when only `issuer` is configured.
|
|
@@ -60,6 +60,13 @@ __exportStar(require("./client"), exports);
|
|
|
60
60
|
var testing_1 = require("./testing");
|
|
61
61
|
Object.defineProperty(exports, "createTestIssuer", { enumerable: true, get: function () { return testing_1.createTestIssuer; } });
|
|
62
62
|
Object.defineProperty(exports, "TEST_TOKEN_TAMPERS", { enumerable: true, get: function () { return testing_1.TEST_TOKEN_TAMPERS; } });
|
|
63
|
+
var referral_test_calls_1 = require("./referral-test-calls");
|
|
64
|
+
Object.defineProperty(exports, "signAtlasReferralCall", { enumerable: true, get: function () { return referral_test_calls_1.signAtlasReferralCall; } });
|
|
65
|
+
Object.defineProperty(exports, "signReferallyCall", { enumerable: true, get: function () { return referral_test_calls_1.signReferallyCall; } });
|
|
66
|
+
Object.defineProperty(exports, "signReferralUpdatedEvent", { enumerable: true, get: function () { return referral_test_calls_1.signReferralUpdatedEvent; } });
|
|
67
|
+
Object.defineProperty(exports, "referallySignature", { enumerable: true, get: function () { return referral_test_calls_1.referallySignature; } });
|
|
68
|
+
Object.defineProperty(exports, "referralEmailHash", { enumerable: true, get: function () { return referral_test_calls_1.referralEmailHash; } });
|
|
69
|
+
Object.defineProperty(exports, "REFERALLY_API_VERSION", { enumerable: true, get: function () { return referral_test_calls_1.REFERALLY_API_VERSION; } });
|
|
63
70
|
// Proof-Carrying Authority (agentic auth): offline verifier + framework-agnostic guard,
|
|
64
71
|
// beside the session-token verifier above.
|
|
65
72
|
var verify_1 = require("./pca/verify");
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,mEAAmE;AACnE,yCAA2G;AAAlG,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,yHAAA,4BAA4B,OAAA;AACrF,2CAAyB;AACzB,8CAA4B;AAE5B,6EAA6E;AAC7E,+CAOwB;AANtB,wHAAA,wBAAwB,OAAA;AACxB,+HAAA,+BAA+B,OAAA;AAC/B,4HAAA,4BAA4B,OAAA;AAC5B,mHAAA,mBAAmB,OAAA;AACnB,uHAAA,uBAAuB,OAAA;AACvB,iHAAA,iBAAiB,OAAA;AAUnB,sEAAsE;AACtE,iFAAiF;AACjF,+BAWgB;AAVd,sGAAA,cAAc,OAAA;AACd,wGAAA,gBAAgB,OAAA;AAChB,iHAAA,yBAAyB,OAAA;AACzB,4FAAA,IAAI,OAAA;AACJ,oGAAA,YAAY,OAAA;AACZ,uGAAA,eAAe,OAAA;AACf,qGAAA,aAAa,OAAA;AACb,iGAAA,SAAS,OAAA;AACT,yGAAA,iBAAiB,OAAA;AACjB,uGAAA,eAAe,OAAA;AAcjB,oDAAoD;AACpD,6CAA2B;AAE3B,uFAAuF;AACvF,8CAA4B;AAE5B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB;AAEzB,yEAAyE;AACzE,2EAA2E;AAC3E,iEAAiE;AACjE,qCAAiE;AAAxD,2GAAA,gBAAgB,OAAA;AAAE,6GAAA,kBAAkB,OAAA;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,mEAAmE;AACnE,yCAA2G;AAAlG,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,yHAAA,4BAA4B,OAAA;AACrF,2CAAyB;AACzB,8CAA4B;AAE5B,6EAA6E;AAC7E,+CAOwB;AANtB,wHAAA,wBAAwB,OAAA;AACxB,+HAAA,+BAA+B,OAAA;AAC/B,4HAAA,4BAA4B,OAAA;AAC5B,mHAAA,mBAAmB,OAAA;AACnB,uHAAA,uBAAuB,OAAA;AACvB,iHAAA,iBAAiB,OAAA;AAUnB,sEAAsE;AACtE,iFAAiF;AACjF,+BAWgB;AAVd,sGAAA,cAAc,OAAA;AACd,wGAAA,gBAAgB,OAAA;AAChB,iHAAA,yBAAyB,OAAA;AACzB,4FAAA,IAAI,OAAA;AACJ,oGAAA,YAAY,OAAA;AACZ,uGAAA,eAAe,OAAA;AACf,qGAAA,aAAa,OAAA;AACb,iGAAA,SAAS,OAAA;AACT,yGAAA,iBAAiB,OAAA;AACjB,uGAAA,eAAe,OAAA;AAcjB,oDAAoD;AACpD,6CAA2B;AAE3B,uFAAuF;AACvF,8CAA4B;AAE5B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB;AAEzB,yEAAyE;AACzE,2EAA2E;AAC3E,iEAAiE;AACjE,qCAAiE;AAAxD,2GAAA,gBAAgB,OAAA;AAAE,6GAAA,kBAAkB,OAAA;AAS7C,6DAO+B;AAN7B,4HAAA,qBAAqB,OAAA;AACrB,wHAAA,iBAAiB,OAAA;AACjB,+HAAA,wBAAwB,OAAA;AACxB,yHAAA,kBAAkB,OAAA;AAClB,wHAAA,iBAAiB,OAAA;AACjB,4HAAA,qBAAqB,OAAA;AAWvB,wFAAwF;AACxF,2CAA2C;AAC3C,uCAA4C;AAAnC,sGAAA,YAAY,OAAA;AAErB,iDAA+E;AAAtE,yGAAA,UAAU,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,6GAAA,cAAc,OAAA"}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { type ReferralOp } from './referrals';
|
|
2
|
+
/**
|
|
3
|
+
* Signed referral calls for an app's own test suite: send exactly what an
|
|
4
|
+
* Atlas instance would send to a referral platform, against a platform you run
|
|
5
|
+
* locally, with no Atlas instance involved. Two wire formats:
|
|
6
|
+
*
|
|
7
|
+
* - the Atlas referral protocol (provider `webhook`): every call is a signed
|
|
8
|
+
* `POST {base}/<endpoint>` with `op` and `customerRef` in the body, signed
|
|
9
|
+
* like Atlas webhooks (`atlas-id`, `atlas-timestamp`, `atlas-signature`);
|
|
10
|
+
* - Referally (provider `referally`): `{base}/v1/auth/connections/{id}/…`,
|
|
11
|
+
* signed with `x-referally-signature: t=<unix s>,v1=<hex HMAC-SHA256>` over
|
|
12
|
+
* `"{t}.{payload}"`, where payload is the raw body for POST and the raw
|
|
13
|
+
* query string for GET.
|
|
14
|
+
*
|
|
15
|
+
* Both are also on {@link TestIssuer} (`referralCall`, `referallyCall`) with
|
|
16
|
+
* the issuer's clock.
|
|
17
|
+
*/
|
|
18
|
+
/** A ready-to-send signed call. `request()` builds a Fetch `Request`. */
|
|
19
|
+
export interface SignedReferralCall {
|
|
20
|
+
url: string;
|
|
21
|
+
method: 'POST' | 'GET';
|
|
22
|
+
headers: Record<string, string>;
|
|
23
|
+
/** The exact signed body (absent on GET). */
|
|
24
|
+
body?: string;
|
|
25
|
+
request(): Request;
|
|
26
|
+
}
|
|
27
|
+
/** sha256 hex of the lower-cased, trimmed email, as Atlas sends `emailHash`. */
|
|
28
|
+
export declare function referralEmailHash(email: string | null | undefined): string | null;
|
|
29
|
+
export interface AtlasReferralCallOptions {
|
|
30
|
+
/** The platform's base URL, as configured on the instance (`endpoint_url`). */
|
|
31
|
+
baseUrl: string;
|
|
32
|
+
/** The instance's signing secret for the connection. */
|
|
33
|
+
secret: string;
|
|
34
|
+
op: ReferralOp;
|
|
35
|
+
/** The rest of the body (`customerRef` and the op's fields); `op` is added. */
|
|
36
|
+
payload: {
|
|
37
|
+
customerRef: string;
|
|
38
|
+
} & Record<string, unknown>;
|
|
39
|
+
/** The call id (`atlas-id`), the same on every retry of one call. Default: random. */
|
|
40
|
+
callId?: string;
|
|
41
|
+
/** Epoch ms. Default: now. */
|
|
42
|
+
now?: number;
|
|
43
|
+
}
|
|
44
|
+
/** A call in the Atlas referral protocol, signed exactly as an Atlas instance signs it. */
|
|
45
|
+
export declare function signAtlasReferralCall(options: AtlasReferralCallOptions): SignedReferralCall;
|
|
46
|
+
/** The Referally API version Atlas pins on every call (`referally-version`). */
|
|
47
|
+
export declare const REFERALLY_API_VERSION = "2026-10-21";
|
|
48
|
+
/** The Referally connection calls Atlas makes. */
|
|
49
|
+
export type ReferallyCallOp = 'signups' | 'erase' | 'export' | 'aliases' | 'users' | 'ping';
|
|
50
|
+
export interface ReferallyCallOptions {
|
|
51
|
+
/** Your Referally base URL (never hard-code it; read it from config). */
|
|
52
|
+
baseUrl: string;
|
|
53
|
+
/** The Atlas connection id on Referally. */
|
|
54
|
+
connectionId: string;
|
|
55
|
+
/** The connection secret Referally returned when the connection was created. */
|
|
56
|
+
secret: string;
|
|
57
|
+
op: ReferallyCallOp;
|
|
58
|
+
/** The JSON body for POST calls. */
|
|
59
|
+
body?: Record<string, unknown>;
|
|
60
|
+
/** `export` only: the customer to export (sent as `?customerRef=`). */
|
|
61
|
+
customerRef?: string;
|
|
62
|
+
/** Epoch ms. Default: now. */
|
|
63
|
+
now?: number;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The `x-referally-signature` value for a payload: `t=<unix s>,v1=<hex
|
|
67
|
+
* HMAC-SHA256(secret, "{t}.{payload}")>`.
|
|
68
|
+
*/
|
|
69
|
+
export declare function referallySignature(secret: string, payload: string, unixSeconds: number): string;
|
|
70
|
+
/** A Referally connection call, signed exactly as the Atlas `referally` adapter signs it. */
|
|
71
|
+
export declare function signReferallyCall(options: ReferallyCallOptions): SignedReferralCall;
|
|
72
|
+
/** The fields of a `referral.updated` event; absent fields stay unchanged on the Atlas side. */
|
|
73
|
+
export interface ReferralUpdatedEvent {
|
|
74
|
+
/** The user's `customerRef` (as Atlas sent it on sign-up). This or `referralId` names the referral. */
|
|
75
|
+
customerRef?: string;
|
|
76
|
+
/** The platform's referral id. */
|
|
77
|
+
referralId?: string;
|
|
78
|
+
programId?: string;
|
|
79
|
+
/** The referral's status on the platform (e.g. `qualified`). */
|
|
80
|
+
status?: string;
|
|
81
|
+
partnerId?: string;
|
|
82
|
+
/** The referrer's `customerRef`, when the referrer is an Atlas user. */
|
|
83
|
+
referrerExternalRef?: string;
|
|
84
|
+
matchedVia?: string;
|
|
85
|
+
}
|
|
86
|
+
export interface ReferralUpdatedEventOptions {
|
|
87
|
+
/** The instance's inbound URL (`inbound.url` on the referral settings). */
|
|
88
|
+
inboundUrl: string;
|
|
89
|
+
/** The inbound secret, or the connection's signing secret when no inbound secret is set. */
|
|
90
|
+
secret: string;
|
|
91
|
+
event: ReferralUpdatedEvent;
|
|
92
|
+
/** When the change happened (ISO 8601 or epoch ms). Default: `now`. Atlas ignores events older than the last one applied. */
|
|
93
|
+
occurredAt?: string | number;
|
|
94
|
+
/** The event id (`atlas-id`), the same on every retry. Default: random. */
|
|
95
|
+
eventId?: string;
|
|
96
|
+
/** Epoch ms. Default: now. */
|
|
97
|
+
now?: number;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Two-way sync: a `referral.updated` event from the platform to an Atlas
|
|
101
|
+
* instance's inbound URL, signed like Atlas webhooks (`atlas-id`,
|
|
102
|
+
* `atlas-timestamp` in ms, `atlas-signature: v1,<base64 HMAC-SHA256 of
|
|
103
|
+
* "{id}.{ts}.{body}">`). Use it in a platform built on the Atlas referral
|
|
104
|
+
* protocol to send referral changes made after sign-up, or in its tests.
|
|
105
|
+
*/
|
|
106
|
+
export declare function signReferralUpdatedEvent(options: ReferralUpdatedEventOptions): SignedReferralCall;
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.REFERALLY_API_VERSION = void 0;
|
|
4
|
+
exports.referralEmailHash = referralEmailHash;
|
|
5
|
+
exports.signAtlasReferralCall = signAtlasReferralCall;
|
|
6
|
+
exports.referallySignature = referallySignature;
|
|
7
|
+
exports.signReferallyCall = signReferallyCall;
|
|
8
|
+
exports.signReferralUpdatedEvent = signReferralUpdatedEvent;
|
|
9
|
+
const node_crypto_1 = require("node:crypto");
|
|
10
|
+
const referrals_1 = require("./referrals");
|
|
11
|
+
function signed(url, method, headers, body) {
|
|
12
|
+
return {
|
|
13
|
+
url,
|
|
14
|
+
method,
|
|
15
|
+
headers,
|
|
16
|
+
body,
|
|
17
|
+
request: () => new Request(url, { method, headers, body }),
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
const trimBase = (base) => base.replace(/\/+$/, '');
|
|
21
|
+
/** sha256 hex of the lower-cased, trimmed email, as Atlas sends `emailHash`. */
|
|
22
|
+
function referralEmailHash(email) {
|
|
23
|
+
if (!email)
|
|
24
|
+
return null;
|
|
25
|
+
return (0, node_crypto_1.createHash)('sha256').update(email.trim().toLowerCase()).digest('hex');
|
|
26
|
+
}
|
|
27
|
+
/** A call in the Atlas referral protocol, signed exactly as an Atlas instance signs it. */
|
|
28
|
+
function signAtlasReferralCall(options) {
|
|
29
|
+
const id = options.callId ?? `rfc_test_${(0, node_crypto_1.randomBytes)(8).toString('hex')}`;
|
|
30
|
+
const timestamp = options.now ?? Date.now();
|
|
31
|
+
const body = JSON.stringify({ op: options.op, ...options.payload });
|
|
32
|
+
const signature = (0, node_crypto_1.createHmac)('sha256', options.secret).update(`${id}.${timestamp}.${body}`).digest('base64');
|
|
33
|
+
const headers = {
|
|
34
|
+
'content-type': 'application/json',
|
|
35
|
+
'atlas-id': id,
|
|
36
|
+
'atlas-timestamp': String(timestamp),
|
|
37
|
+
'atlas-signature': `v1,${signature}`,
|
|
38
|
+
'idempotency-key': `${options.op}:${options.payload.customerRef}`,
|
|
39
|
+
'user-agent': referrals_1.REFERRAL_PROTOCOL_USER_AGENT,
|
|
40
|
+
[referrals_1.REFERRAL_PROTOCOL_VERSION_HEADER]: referrals_1.REFERRAL_PROTOCOL_VERSION,
|
|
41
|
+
};
|
|
42
|
+
return signed(`${trimBase(options.baseUrl)}/${referrals_1.REFERRAL_OP_ENDPOINTS[options.op]}`, 'POST', headers, body);
|
|
43
|
+
}
|
|
44
|
+
/** The Referally API version Atlas pins on every call (`referally-version`). */
|
|
45
|
+
exports.REFERALLY_API_VERSION = '2026-10-21';
|
|
46
|
+
/**
|
|
47
|
+
* The `x-referally-signature` value for a payload: `t=<unix s>,v1=<hex
|
|
48
|
+
* HMAC-SHA256(secret, "{t}.{payload}")>`.
|
|
49
|
+
*/
|
|
50
|
+
function referallySignature(secret, payload, unixSeconds) {
|
|
51
|
+
const mac = (0, node_crypto_1.createHmac)('sha256', secret).update(`${unixSeconds}.${payload}`).digest('hex');
|
|
52
|
+
return `t=${unixSeconds},v1=${mac}`;
|
|
53
|
+
}
|
|
54
|
+
/** A Referally connection call, signed exactly as the Atlas `referally` adapter signs it. */
|
|
55
|
+
function signReferallyCall(options) {
|
|
56
|
+
const t = Math.floor((options.now ?? Date.now()) / 1000);
|
|
57
|
+
const base = `${trimBase(options.baseUrl)}/v1/auth/connections/${encodeURIComponent(options.connectionId)}/${options.op}`;
|
|
58
|
+
const headers = { 'referally-version': exports.REFERALLY_API_VERSION };
|
|
59
|
+
if (options.op === 'export') {
|
|
60
|
+
if (!options.customerRef)
|
|
61
|
+
throw new Error('signReferallyCall: export needs customerRef.');
|
|
62
|
+
const query = new URLSearchParams({ customerRef: options.customerRef }).toString();
|
|
63
|
+
headers['x-referally-signature'] = referallySignature(options.secret, query, t);
|
|
64
|
+
return signed(`${base}?${query}`, 'GET', headers);
|
|
65
|
+
}
|
|
66
|
+
const body = JSON.stringify(options.body ?? {});
|
|
67
|
+
headers['content-type'] = 'application/json';
|
|
68
|
+
headers['x-referally-signature'] = referallySignature(options.secret, body, t);
|
|
69
|
+
return signed(base, 'POST', headers, body);
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Two-way sync: a `referral.updated` event from the platform to an Atlas
|
|
73
|
+
* instance's inbound URL, signed like Atlas webhooks (`atlas-id`,
|
|
74
|
+
* `atlas-timestamp` in ms, `atlas-signature: v1,<base64 HMAC-SHA256 of
|
|
75
|
+
* "{id}.{ts}.{body}">`). Use it in a platform built on the Atlas referral
|
|
76
|
+
* protocol to send referral changes made after sign-up, or in its tests.
|
|
77
|
+
*/
|
|
78
|
+
function signReferralUpdatedEvent(options) {
|
|
79
|
+
const { event } = options;
|
|
80
|
+
if (!event.customerRef && !event.referralId) {
|
|
81
|
+
throw new Error('signReferralUpdatedEvent: the event needs customerRef or referralId.');
|
|
82
|
+
}
|
|
83
|
+
const id = options.eventId ?? `rfe_${(0, node_crypto_1.randomBytes)(8).toString('hex')}`;
|
|
84
|
+
const timestamp = options.now ?? Date.now();
|
|
85
|
+
const occurred = options.occurredAt ?? timestamp;
|
|
86
|
+
const body = JSON.stringify({
|
|
87
|
+
type: 'referral.updated',
|
|
88
|
+
occurredAt: typeof occurred === 'number' ? new Date(occurred).toISOString() : occurred,
|
|
89
|
+
...event,
|
|
90
|
+
});
|
|
91
|
+
const signature = (0, node_crypto_1.createHmac)('sha256', options.secret).update(`${id}.${timestamp}.${body}`).digest('base64');
|
|
92
|
+
const headers = {
|
|
93
|
+
'content-type': 'application/json',
|
|
94
|
+
'atlas-id': id,
|
|
95
|
+
'atlas-timestamp': String(timestamp),
|
|
96
|
+
'atlas-signature': `v1,${signature}`,
|
|
97
|
+
'user-agent': referrals_1.REFERRAL_PROTOCOL_USER_AGENT,
|
|
98
|
+
[referrals_1.REFERRAL_PROTOCOL_VERSION_HEADER]: referrals_1.REFERRAL_PROTOCOL_VERSION,
|
|
99
|
+
};
|
|
100
|
+
return signed(options.inboundUrl, 'POST', headers, body);
|
|
101
|
+
}
|
|
102
|
+
//# sourceMappingURL=referral-test-calls.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"referral-test-calls.js","sourceRoot":"","sources":["../src/referral-test-calls.ts"],"names":[],"mappings":"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"}
|
package/dist/referrals.d.ts
CHANGED
|
@@ -11,13 +11,17 @@ import type { ReferralRisk } from './client/referrals';
|
|
|
11
11
|
* POST {base}/export { op: 'export', customerRef, test } → 200 JSON (any shape) | 404
|
|
12
12
|
* POST {base}/partners { op: 'partner', customerRef, code, emailHash } → 2xx | 409 code taken | 404/405/501 unsupported
|
|
13
13
|
* POST {base}/signals { op: 'signal', customerRef, type, occurredAt, data } → 2xx | 404/405/501 unsupported
|
|
14
|
+
* POST {base}/aliases { op: 'alias', customerRef, fromCustomerRef, toCustomerRef } → 2xx | 409 (permanent)
|
|
15
|
+
* POST {base}/users { op: 'user', customerRef, email?, name?, status? } → 2xx
|
|
16
|
+
* POST {base}/ping { op: 'ping', customerRef: 'atlas_connection_test' } → 200 ReferralPingResponse
|
|
14
17
|
*
|
|
15
18
|
* The connection test is `POST {base}/export` with
|
|
16
19
|
* `{ op: 'export', customerRef: 'atlas_connection_test', test: true }` (answer
|
|
17
20
|
* 2xx or 404). Calls are signed exactly like Atlas webhooks (`atlas-id`,
|
|
18
21
|
* `atlas-timestamp`, `atlas-signature` over `<id>.<timestamp>.<raw body>`),
|
|
19
|
-
* with `Idempotency-Key
|
|
20
|
-
* call id, the same on
|
|
22
|
+
* with `Idempotency-Key`, `User-Agent: Atlas-Referrals/1` and
|
|
23
|
+
* `Atlas-Referrals-Version: 2026-10-21`. `atlas-id` is the call id, the same on
|
|
24
|
+
* every retry of one call.
|
|
21
25
|
*
|
|
22
26
|
* The signature covers the body, not the URL, so everything that matters is in
|
|
23
27
|
* the body. Pass the path the request arrived on (or the operation you
|
|
@@ -28,6 +32,10 @@ import type { ReferralRisk } from './client/referrals';
|
|
|
28
32
|
export declare const REFERRAL_CONNECTION_TEST_REF = "atlas_connection_test";
|
|
29
33
|
/** The `User-Agent` Atlas sends on every referral call. */
|
|
30
34
|
export declare const REFERRAL_PROTOCOL_USER_AGENT = "Atlas-Referrals/1";
|
|
35
|
+
/** The `Atlas-Referrals-Version` header Atlas sends on every call; shapes only grow, additively, under it. */
|
|
36
|
+
export declare const REFERRAL_PROTOCOL_VERSION = "2026-10-21";
|
|
37
|
+
/** The name of the version header (lower-case). */
|
|
38
|
+
export declare const REFERRAL_PROTOCOL_VERSION_HEADER = "atlas-referrals-version";
|
|
31
39
|
/** The referral captured at sign-up (from the page URL, or a tracking cookie under consent). Never trusted. */
|
|
32
40
|
export interface ReferralContext {
|
|
33
41
|
/** The referral code from the URL (or cookie), 3-64 of `A-Z a-z 0-9 _ -`. */
|
|
@@ -82,6 +90,8 @@ export interface ReferralSignupResponse {
|
|
|
82
90
|
code: string | null;
|
|
83
91
|
link?: string | null;
|
|
84
92
|
} | null;
|
|
93
|
+
/** Why you matched or did not (shown in the Atlas delivery log and on the user). */
|
|
94
|
+
notes?: string[];
|
|
85
95
|
}
|
|
86
96
|
/** `POST {base}/erase`. */
|
|
87
97
|
export interface ReferralErasePayload {
|
|
@@ -113,8 +123,46 @@ export interface ReferralSignalPayload {
|
|
|
113
123
|
occurredAt: string;
|
|
114
124
|
data: Record<string, unknown>;
|
|
115
125
|
}
|
|
126
|
+
/**
|
|
127
|
+
* `POST {base}/aliases`: the user's `external_id` was set or changed after the
|
|
128
|
+
* sign-up call. Re-key the customer from `fromCustomerRef` (the old value, or
|
|
129
|
+
* the Atlas user id) to `toCustomerRef`. `customerRef` equals `toCustomerRef`.
|
|
130
|
+
* A 409 is treated as permanent.
|
|
131
|
+
*/
|
|
132
|
+
export interface ReferralAliasPayload {
|
|
133
|
+
op: 'alias';
|
|
134
|
+
customerRef: string;
|
|
135
|
+
fromCustomerRef: string;
|
|
136
|
+
toCustomerRef: string;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* `POST {base}/users`: a lifecycle change. `email` / `name` when they changed;
|
|
140
|
+
* `status` `suspended` on a ban, `active` on an unban, `deleted` on deletion
|
|
141
|
+
* (deletion is also sent to `/erase`).
|
|
142
|
+
*/
|
|
143
|
+
export interface ReferralUserPayload {
|
|
144
|
+
op: 'user';
|
|
145
|
+
customerRef: string;
|
|
146
|
+
email?: string | null;
|
|
147
|
+
name?: string | null;
|
|
148
|
+
status?: 'active' | 'suspended' | 'deleted';
|
|
149
|
+
}
|
|
150
|
+
/** `POST {base}/ping`: the connection test where the platform supports it. */
|
|
151
|
+
export interface ReferralPingPayload {
|
|
152
|
+
op: 'ping';
|
|
153
|
+
customerRef: string;
|
|
154
|
+
}
|
|
155
|
+
/** The answer to a ping. Every field but `ok` is optional and shown on the Atlas dashboard. */
|
|
156
|
+
export interface ReferralPingResponse {
|
|
157
|
+
ok: boolean;
|
|
158
|
+
programName?: string;
|
|
159
|
+
orgName?: string;
|
|
160
|
+
autoEnrollUsers?: boolean;
|
|
161
|
+
/** ISO 8601. Atlas warns when it is more than 60 seconds off. */
|
|
162
|
+
serverTime?: string;
|
|
163
|
+
}
|
|
116
164
|
/** The operations of the referral protocol (the `op` of every call). */
|
|
117
|
-
export type ReferralOp = 'signup' | 'erase' | 'export' | 'partner' | 'signal';
|
|
165
|
+
export type ReferralOp = 'signup' | 'erase' | 'export' | 'partner' | 'signal' | 'alias' | 'user' | 'ping';
|
|
118
166
|
/** The endpoint (last path segment) each operation is sent to. */
|
|
119
167
|
export declare const REFERRAL_OP_ENDPOINTS: Record<ReferralOp, string>;
|
|
120
168
|
/** A verified call, by operation. */
|
|
@@ -135,6 +183,15 @@ export type ReferralProtocolCall = {
|
|
|
135
183
|
} | {
|
|
136
184
|
op: 'signal';
|
|
137
185
|
payload: ReferralSignalPayload;
|
|
186
|
+
} | {
|
|
187
|
+
op: 'alias';
|
|
188
|
+
payload: ReferralAliasPayload;
|
|
189
|
+
} | {
|
|
190
|
+
op: 'user';
|
|
191
|
+
payload: ReferralUserPayload;
|
|
192
|
+
} | {
|
|
193
|
+
op: 'ping';
|
|
194
|
+
payload: ReferralPingPayload;
|
|
138
195
|
};
|
|
139
196
|
/**
|
|
140
197
|
* Why a call was refused: a webhook signature failure, or
|
|
@@ -153,8 +210,8 @@ export interface VerifyReferralRequestInput {
|
|
|
153
210
|
secret: string;
|
|
154
211
|
/**
|
|
155
212
|
* The path (or full URL) the request arrived on, e.g. `req.path`. Its last
|
|
156
|
-
* segment (`signups`, `erase`, `export`, `partners`, `signals`
|
|
157
|
-
* the signed `op`.
|
|
213
|
+
* segment (`signups`, `erase`, `export`, `partners`, `signals`, `aliases`,
|
|
214
|
+
* `users`, `ping`) must match the signed `op`.
|
|
158
215
|
*/
|
|
159
216
|
path?: string;
|
|
160
217
|
/** The operation this handler serves; the signed `op` must equal it. */
|
|
@@ -172,6 +229,8 @@ export interface ReferralVerifyResult {
|
|
|
172
229
|
timestamp?: number;
|
|
173
230
|
/** The `Idempotency-Key` header (`signup:<customerRef>` on sign-ups). Not signed. */
|
|
174
231
|
idempotencyKey?: string;
|
|
232
|
+
/** The `Atlas-Referrals-Version` header, when sent. Not signed. */
|
|
233
|
+
protocolVersion?: string;
|
|
175
234
|
/** The operation and its payload, present only when `verified`. */
|
|
176
235
|
call?: ReferralProtocolCall;
|
|
177
236
|
}
|
|
@@ -191,7 +250,8 @@ export declare function referralOpForPath(path: string): ReferralOp | null;
|
|
|
191
250
|
* if (!verified || !call) return res.sendStatus(401);
|
|
192
251
|
* if (call.op === 'export' && call.test) return res.sendStatus(404);
|
|
193
252
|
* if (call.op === 'signup') return res.json(await attribute(call.payload)); // ReferralSignupResponse
|
|
194
|
-
*
|
|
253
|
+
* if (call.op === 'ping') return res.json({ ok: true, serverTime: new Date().toISOString() });
|
|
254
|
+
* // erase, export, partner, signal, alias, user ...
|
|
195
255
|
* });
|
|
196
256
|
* ```
|
|
197
257
|
*/
|
package/dist/referrals.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.REFERRAL_OP_ENDPOINTS = exports.REFERRAL_PROTOCOL_USER_AGENT = exports.REFERRAL_CONNECTION_TEST_REF = void 0;
|
|
3
|
+
exports.REFERRAL_OP_ENDPOINTS = exports.REFERRAL_PROTOCOL_VERSION_HEADER = exports.REFERRAL_PROTOCOL_VERSION = exports.REFERRAL_PROTOCOL_USER_AGENT = exports.REFERRAL_CONNECTION_TEST_REF = void 0;
|
|
4
4
|
exports.referralOpForPath = referralOpForPath;
|
|
5
5
|
exports.verifyReferralRequest = verifyReferralRequest;
|
|
6
6
|
const webhooks_1 = require("./webhooks");
|
|
@@ -15,13 +15,17 @@ const webhooks_1 = require("./webhooks");
|
|
|
15
15
|
* POST {base}/export { op: 'export', customerRef, test } → 200 JSON (any shape) | 404
|
|
16
16
|
* POST {base}/partners { op: 'partner', customerRef, code, emailHash } → 2xx | 409 code taken | 404/405/501 unsupported
|
|
17
17
|
* POST {base}/signals { op: 'signal', customerRef, type, occurredAt, data } → 2xx | 404/405/501 unsupported
|
|
18
|
+
* POST {base}/aliases { op: 'alias', customerRef, fromCustomerRef, toCustomerRef } → 2xx | 409 (permanent)
|
|
19
|
+
* POST {base}/users { op: 'user', customerRef, email?, name?, status? } → 2xx
|
|
20
|
+
* POST {base}/ping { op: 'ping', customerRef: 'atlas_connection_test' } → 200 ReferralPingResponse
|
|
18
21
|
*
|
|
19
22
|
* The connection test is `POST {base}/export` with
|
|
20
23
|
* `{ op: 'export', customerRef: 'atlas_connection_test', test: true }` (answer
|
|
21
24
|
* 2xx or 404). Calls are signed exactly like Atlas webhooks (`atlas-id`,
|
|
22
25
|
* `atlas-timestamp`, `atlas-signature` over `<id>.<timestamp>.<raw body>`),
|
|
23
|
-
* with `Idempotency-Key
|
|
24
|
-
* call id, the same on
|
|
26
|
+
* with `Idempotency-Key`, `User-Agent: Atlas-Referrals/1` and
|
|
27
|
+
* `Atlas-Referrals-Version: 2026-10-21`. `atlas-id` is the call id, the same on
|
|
28
|
+
* every retry of one call.
|
|
25
29
|
*
|
|
26
30
|
* The signature covers the body, not the URL, so everything that matters is in
|
|
27
31
|
* the body. Pass the path the request arrived on (or the operation you
|
|
@@ -32,6 +36,10 @@ const webhooks_1 = require("./webhooks");
|
|
|
32
36
|
exports.REFERRAL_CONNECTION_TEST_REF = 'atlas_connection_test';
|
|
33
37
|
/** The `User-Agent` Atlas sends on every referral call. */
|
|
34
38
|
exports.REFERRAL_PROTOCOL_USER_AGENT = 'Atlas-Referrals/1';
|
|
39
|
+
/** The `Atlas-Referrals-Version` header Atlas sends on every call; shapes only grow, additively, under it. */
|
|
40
|
+
exports.REFERRAL_PROTOCOL_VERSION = '2026-10-21';
|
|
41
|
+
/** The name of the version header (lower-case). */
|
|
42
|
+
exports.REFERRAL_PROTOCOL_VERSION_HEADER = 'atlas-referrals-version';
|
|
35
43
|
/** The endpoint (last path segment) each operation is sent to. */
|
|
36
44
|
exports.REFERRAL_OP_ENDPOINTS = {
|
|
37
45
|
signup: 'signups',
|
|
@@ -39,6 +47,9 @@ exports.REFERRAL_OP_ENDPOINTS = {
|
|
|
39
47
|
export: 'export',
|
|
40
48
|
partner: 'partners',
|
|
41
49
|
signal: 'signals',
|
|
50
|
+
alias: 'aliases',
|
|
51
|
+
user: 'users',
|
|
52
|
+
ping: 'ping',
|
|
42
53
|
};
|
|
43
54
|
function header(headers, name) {
|
|
44
55
|
if (typeof headers.get === 'function')
|
|
@@ -76,7 +87,8 @@ function referralOpForPath(path) {
|
|
|
76
87
|
* if (!verified || !call) return res.sendStatus(401);
|
|
77
88
|
* if (call.op === 'export' && call.test) return res.sendStatus(404);
|
|
78
89
|
* if (call.op === 'signup') return res.json(await attribute(call.payload)); // ReferralSignupResponse
|
|
79
|
-
*
|
|
90
|
+
* if (call.op === 'ping') return res.json({ ok: true, serverTime: new Date().toISOString() });
|
|
91
|
+
* // erase, export, partner, signal, alias, user ...
|
|
80
92
|
* });
|
|
81
93
|
* ```
|
|
82
94
|
*/
|
|
@@ -115,6 +127,7 @@ function verifyReferralRequest(input) {
|
|
|
115
127
|
deliveryId: result.deliveryId,
|
|
116
128
|
timestamp: result.timestamp,
|
|
117
129
|
idempotencyKey: header(input.headers, 'idempotency-key'),
|
|
130
|
+
protocolVersion: header(input.headers, exports.REFERRAL_PROTOCOL_VERSION_HEADER),
|
|
118
131
|
call,
|
|
119
132
|
};
|
|
120
133
|
}
|
package/dist/referrals.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"referrals.js","sourceRoot":"","sources":["../src/referrals.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"referrals.js","sourceRoot":"","sources":["../src/referrals.ts"],"names":[],"mappings":"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"}
|