@forumulate/sdk 0.13.8 → 0.14.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 CHANGED
@@ -3,6 +3,12 @@
3
3
  Releases of `@forumulate/sdk`. Earlier versions are described in the git history of
4
4
  `packages/sdk` (`release(sdk): …` commits).
5
5
 
6
+ ## 0.14.0
7
+
8
+ - `pingHeartbeat({ url, token, ok?, detail?, timeoutMs? })`: one heartbeat ping, for the end of a scheduled job. It never throws, waits at most 5 s by default, and answers `{ delivered, status?, error? }`. `startHeartbeat` now pings through it.
9
+ - Heartbeat monitors take `graceSeconds`. The monitor reads down after `intervalSeconds + graceSeconds` of silence; the default is still 1.5x the interval.
10
+ - `orgProvisioningKey` on the consent connect is described as what it is: a Cookie Munch org key, issued by Cookie Munch.
11
+
6
12
  ## 0.13.2
7
13
 
8
14
  - An authenticated write now refuses a query parameter it does not read: `400`
@@ -30,7 +30,7 @@ export interface StartHeartbeatOptions {
30
30
  url: string;
31
31
  /** The monitor's `pingToken`, sent as `Authorization: Bearer`. Keep it in a secret store. */
32
32
  token?: string;
33
- /** Interval between pings. Ping at least once per monitor interval; the monitor goes down after 1.5x. */
33
+ /** Interval between pings. Ping at least once per monitor interval; the monitor goes down after interval + its `graceSeconds` (default 1.5x). */
34
34
  everyMs: number;
35
35
  /** Is the job healthy? Throwing is reported as a failed pass. Omit to ping a plain `ok`. */
36
36
  check?: () => Promise<HeartbeatCheckResult> | HeartbeatCheckResult;
@@ -41,5 +41,29 @@ export interface StartHeartbeatOptions {
41
41
  /** For a runtime without a global `fetch`, and for tests. */
42
42
  fetch?: typeof fetch;
43
43
  }
44
+ export interface PingHeartbeatOptions {
45
+ /** The monitor's `pingEndpoint` with `token` (preferred), or its `pingUrl`, which holds the secret. */
46
+ url: string;
47
+ /** The monitor's `pingToken`, sent as `Authorization: Bearer`. */
48
+ token?: string;
49
+ /** False reports a run that did not go cleanly (the component reads partial outage with `detail`). */
50
+ ok?: boolean;
51
+ /** Kept to 500 characters; shown to your organization only. */
52
+ detail?: string;
53
+ /** Default 5 000 ms: a status page must never hold up the job it reports on. */
54
+ timeoutMs?: number;
55
+ fetch?: typeof fetch;
56
+ }
57
+ /**
58
+ * One ping after a scheduled run (EmojiDex FO-7): `await pingHeartbeat({url, token})`
59
+ * at the end of a cron job. Never throws and never waits past `timeoutMs`; the
60
+ * answer says whether the ping landed, so the caller may log it. A monitor must
61
+ * never be able to fail the thing it monitors.
62
+ */
63
+ export declare function pingHeartbeat(opts: PingHeartbeatOptions): Promise<{
64
+ delivered: boolean;
65
+ status?: number;
66
+ error?: string;
67
+ }>;
44
68
  export declare function startHeartbeat(opts: StartHeartbeatOptions): () => void;
45
69
  //# sourceMappingURL=heartbeat.d.ts.map
package/dist/heartbeat.js CHANGED
@@ -1,6 +1,31 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.pingHeartbeat = pingHeartbeat;
3
4
  exports.startHeartbeat = startHeartbeat;
5
+ /**
6
+ * One ping after a scheduled run (EmojiDex FO-7): `await pingHeartbeat({url, token})`
7
+ * at the end of a cron job. Never throws and never waits past `timeoutMs`; the
8
+ * answer says whether the ping landed, so the caller may log it. A monitor must
9
+ * never be able to fail the thing it monitors.
10
+ */
11
+ async function pingHeartbeat(opts) {
12
+ try {
13
+ const ok = opts.ok !== false;
14
+ const res = await (opts.fetch ?? globalThis.fetch)(opts.url, {
15
+ method: 'POST',
16
+ headers: {
17
+ 'content-type': 'application/json',
18
+ ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}),
19
+ },
20
+ body: JSON.stringify(ok ? { ok: true } : { ok: false, detail: (opts.detail ?? '').slice(0, 500) }),
21
+ signal: AbortSignal.timeout(opts.timeoutMs ?? 5_000),
22
+ });
23
+ return { delivered: res.ok, status: res.status };
24
+ }
25
+ catch (err) {
26
+ return { delivered: false, error: err instanceof Error ? err.message : String(err) };
27
+ }
28
+ }
4
29
  function startHeartbeat(opts) {
5
30
  const doFetch = opts.fetch ?? globalThis.fetch;
6
31
  const timeoutMs = Math.min(opts.timeoutMs ?? 10_000, opts.everyMs);
@@ -18,17 +43,9 @@ function startHeartbeat(opts) {
18
43
  }
19
44
  if (stopped)
20
45
  return;
21
- const res = await doFetch(opts.url, {
22
- method: 'POST',
23
- headers: {
24
- 'content-type': 'application/json',
25
- ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}),
26
- },
27
- body: JSON.stringify(body.ok ? { ok: true } : { ok: false, detail: (body.detail ?? '').slice(0, 500) }),
28
- signal: AbortSignal.timeout(timeoutMs),
29
- });
30
- if (!res.ok)
31
- opts.onError?.(new Error(`heartbeat ping answered ${res.status}`));
46
+ const sent = await pingHeartbeat({ url: opts.url, token: opts.token, ok: body.ok, detail: body.detail, timeoutMs, fetch: doFetch });
47
+ if (!sent.delivered)
48
+ opts.onError?.(new Error(sent.error ?? `heartbeat ping answered ${sent.status}`));
32
49
  }
33
50
  catch (err) {
34
51
  try {
package/dist/http.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * and not another.
7
7
  */
8
8
  /** Kept in step with package.json by `coverage.test.ts`. */
9
- export declare const SDK_VERSION = "0.13.8";
9
+ export declare const SDK_VERSION = "0.14.0";
10
10
  /** The API's error envelope: `{ error: { code, message, details? }, requestId? }`. */
11
11
  export interface ForumulateErrorInit {
12
12
  /** Field-level detail, e.g. `{ title: ['Required'] }` for `validation.failed`. */
package/dist/http.js CHANGED
@@ -11,7 +11,7 @@ exports.EXPORT_WAIT_MS = exports.ForumulateError = exports.SDK_VERSION = void 0;
11
11
  exports.retryDelayMs = retryDelayMs;
12
12
  exports.send = send;
13
13
  /** Kept in step with package.json by `coverage.test.ts`. */
14
- exports.SDK_VERSION = '0.13.8';
14
+ exports.SDK_VERSION = '0.14.0';
15
15
  /**
16
16
  * Thrown for any non-2xx API response, and for a network failure that
17
17
  * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the
@@ -756,6 +756,10 @@ export declare const OPERATIONS: {
756
756
  readonly prefill: "POST ~s/compare/prefill";
757
757
  readonly preview: "GET ~s/compare/preview";
758
758
  }];
759
+ readonly Connect: readonly ["connect", {
760
+ readonly preview: "POST /v1/connect/{partner}/preview";
761
+ readonly approve: "POST /v1/connect/{partner}/approve";
762
+ }];
759
763
  readonly ConnectorKnowledgeAdmin: readonly ["connectorKnowledgeAdmin", {
760
764
  readonly readers: "GET ~s/kb-readers p";
761
765
  readonly rotate: "POST ~o/connector-identity/rotate";
@@ -1372,6 +1376,7 @@ export declare const OPERATIONS: {
1372
1376
  readonly changelogWidget: "GET /embed/changelog.js";
1373
1377
  readonly faqWidget: "GET /embed/faq.js";
1374
1378
  readonly askWidget: "GET /embed/ask.js";
1379
+ readonly sdk: "GET /embed/sdk/{file}";
1375
1380
  readonly check: "GET /embed/check";
1376
1381
  }];
1377
1382
  readonly EmbedFeed: readonly ["embeds.feed", {
@@ -2897,6 +2902,8 @@ export declare const OPERATIONS: {
2897
2902
  readonly auto: "POST ~s/pages/{pageId}/translations/{locale}/auto";
2898
2903
  }];
2899
2904
  readonly PartnerLinks: readonly ["partnerLinks", {
2905
+ readonly rotate: "POST /v1/partner_links/{id}/rotate";
2906
+ readonly renew: "POST /v1/partner_links/{id}/renew";
2900
2907
  readonly create: "POST /v1/partner_links";
2901
2908
  readonly list: "GET /v1/partner_links p";
2902
2909
  readonly get: "GET /v1/partner_links/{id}";
@@ -108,6 +108,7 @@ exports.OPERATIONS = {
108
108
  Reputation: ['community.reputation', { profile: 'GET ~o/community/members/{userId}/profile', catalog: 'GET ~o/community/reputation/catalog', createBadge: 'POST ~o/community/reputation/badges', updateBadge: 'POST ~o/community/reputation/badges/{badgeId}', deleteBadge: 'DELETE ~o/community/reputation/badges/{badgeId}', grantBadge: 'POST ~o/community/reputation/{userId}/badges', revokeBadge: 'DELETE ~o/community/reputation/{userId}/badges/{slug}', recompute: 'POST ~o/community/reputation/recompute', me: 'GET ~o/community/reputation/me', setExternal: 'PUT ~o/community/reputation/{userId}/external', removeExternal: 'DELETE ~o/community/reputation/{userId}/external/{source}', externalLeaderboard: 'GET ~o/community/reputation/external/{source}/leaderboard', getFeatured: 'GET ~o/community/reputation/me/featured', setFeatured: 'PUT ~o/community/reputation/me/featured', setFeaturedTopic: 'PUT ~o/community/reputation/me/featured-topic', setBackgrounds: 'PUT ~o/community/reputation/me/backgrounds', leaderboard: 'GET ~o/community/reputation/leaderboard p', pointsLeaderboard: 'GET ~o/community/reputation/points', directory: 'GET ~o/community/directory p', forUser: 'GET ~o/community/reputation/{userId}', setLevel: 'POST ~o/community/reputation/{userId}/level', unfurlLink: 'GET ~o/community/unfurl' }],
109
109
  ReputationSubject: ['community.reputationSubject', { set: 'PUT ~o/community/reputation/by-subject/external', remove: 'DELETE ~o/community/reputation/by-subject/external', pending: 'GET ~o/community/reputation/by-subject/external/pending p', delete: '=remove DELETE ~o/community/reputation/by-subject/external' }],
110
110
  Compare: ['compare', { catalog: 'GET ~s/compare/catalog', setCatalog: 'PUT ~s/compare/catalog', patchCatalog: 'PATCH ~s/compare/catalog', catalogCsv: 'GET ~s/compare/catalog.csv t', importCsv: 'PUT ~s/compare/catalog.csv', staleCells: 'GET ~s/compare/stale', verify: 'POST ~s/compare/verify', generate: 'POST ~s/compare/generate', prefill: 'POST ~s/compare/prefill', preview: 'GET ~s/compare/preview' }],
111
+ Connect: ['connect', { preview: 'POST /v1/connect/{partner}/preview', approve: 'POST /v1/connect/{partner}/approve' }],
111
112
  ConnectorKnowledgeAdmin: ['connectorKnowledgeAdmin', { readers: 'GET ~s/kb-readers p', rotate: 'POST ~o/connector-identity/rotate' }],
112
113
  ContentAi: ['content.ai', { status: 'GET ~L/ai/status', translate: 'POST ~L/ai/translate', auto: 'POST ~L/entries/{entryId}/translations/{locale}/auto', seo: 'POST ~L/entries/{entryId}/ai/seo', draft: 'POST ~L/entries/{entryId}/ai/draft' }],
113
114
  LibraryAsset: ['content.assetCandidates', { list: 'GET ~L/asset-candidates p' }],
@@ -192,7 +193,7 @@ exports.OPERATIONS = {
192
193
  AcmeChallenge: ['domains.acme', { challenge: 'GET /.well-known/acme-challenge/{token} t' }],
193
194
  PublicDomain: ['domains.public', { primary: 'GET /public/domains/primary', resolve: 'GET /public/domains/resolve' }],
194
195
  DomainTags: ['domains.tags', { spaceDomain: 'PATCH ~s/domains/{domainId}', libraryDomain: 'PATCH ~L/domains/{domainId}', siteDomain: 'PATCH ~o/sites/{siteId}/domains/{domainId}' }],
195
- Embed: ['embeds', { docsWidget: 'GET /embed/widget.js', commentsWidget: 'GET /embed/comments.js', forumWidget: 'GET /embed/forum.js', changelogWidget: 'GET /embed/changelog.js', faqWidget: 'GET /embed/faq.js', askWidget: 'GET /embed/ask.js', check: 'GET /embed/check' }],
196
+ Embed: ['embeds', { docsWidget: 'GET /embed/widget.js', commentsWidget: 'GET /embed/comments.js', forumWidget: 'GET /embed/forum.js', changelogWidget: 'GET /embed/changelog.js', faqWidget: 'GET /embed/faq.js', askWidget: 'GET /embed/ask.js', sdk: 'GET /embed/sdk/{file}', check: 'GET /embed/check' }],
196
197
  EmbedFeed: ['embeds.feed', { list: 'GET ~o/embed-feeds p', add: 'POST ~o/embed-feeds', update: 'PATCH ~o/embed-feeds/{feedId}', remove: 'DELETE ~o/embed-feeds/{feedId}', pollNow: 'POST ~o/embed-feeds/{feedId}/poll', delete: '=remove DELETE ~o/embed-feeds/{feedId}' }],
197
198
  EmbeddableHost: ['embeds.hosts', { list: 'GET ~o/embeddable-hosts p', add: 'POST ~o/embeddable-hosts', remove: 'DELETE ~o/embeddable-hosts/{hostId}', delete: '=remove DELETE ~o/embeddable-hosts/{hostId}' }],
198
199
  Entitlements: ['entitlements', { entitlements: 'GET ~o/entitlements' }],
@@ -399,7 +400,7 @@ exports.OPERATIONS = {
399
400
  Revision: ['pages.revisions', { save: 'PUT ~s/pages/{pageId}/content', putSection: 'PUT ~s/pages/{pageId}/sections/{key}', setShape: 'PUT ~s/pages/{pageId}/shape', draft: 'GET ~s/pages/{pageId}/draft', published: 'GET ~s/pages/{pageId}/published', history: 'GET ~s/pages/{pageId}/revisions p', diff: 'GET ~s/pages/{pageId}/revisions/{revisionId}/diff', checkpoints: 'GET ~s/pages/{pageId}/checkpoints', checkpoint: 'GET ~s/pages/{pageId}/checkpoints/{checkpointId}', restoreCheckpoint: 'POST ~s/pages/{pageId}/checkpoints/{checkpointId}/restore', publish: 'POST ~s/pages/{pageId}/publish', getSchedule: 'GET ~s/pages/{pageId}/schedule', schedule: 'POST ~s/pages/{pageId}/schedule', cancelSchedule: 'DELETE ~s/pages/{pageId}/schedule', rollback: 'POST ~s/pages/{pageId}/rollback' }],
400
401
  PageTemplate: ['pages.template', { list: 'GET ~s/page-templates p', save: 'POST ~s/page-templates', remove: 'DELETE ~s/page-templates/{id}', newPage: 'POST ~s/page-templates/{id}/new-page', delete: '=remove DELETE ~s/page-templates/{id}' }],
401
402
  PageTranslation: ['pages.translation', { list: 'GET ~s/pages/{pageId}/translations p', auto: 'POST ~s/pages/{pageId}/translations/{locale}/auto' }],
402
- PartnerLinks: ['partnerLinks', { create: 'POST /v1/partner_links', list: 'GET /v1/partner_links p', get: 'GET /v1/partner_links/{id}', revoke: 'DELETE /v1/partner_links/{id}', approve: 'POST /v1/partner_links/{id}/approve' }],
403
+ PartnerLinks: ['partnerLinks', { rotate: 'POST /v1/partner_links/{id}/rotate', renew: 'POST /v1/partner_links/{id}/renew', create: 'POST /v1/partner_links', list: 'GET /v1/partner_links p', get: 'GET /v1/partner_links/{id}', revoke: 'DELETE /v1/partner_links/{id}', approve: 'POST /v1/partner_links/{id}/approve' }],
403
404
  PhoneOptins: ['phoneOptins', { options: 'GET ~P/phone-alerts', start: 'POST ~P/phone-alerts', verify: 'POST ~P/phone-alerts/verify', unsubscribe: 'POST ~P/phone-alerts/unsubscribe' }],
404
405
  PlatformChangelog: ['platformChangelog', { list: 'GET /changelog.json p' }],
405
406
  PolicyFeed: ['policyFeed', { atlasFeed: 'GET /atlas/spaces/{spaceId}/policies', signedFeed: 'GET /policy-feed/spaces/{spaceId}/policies', publicFeed: 'GET /public/spaces/{spaceId}/policies', release: 'GET /public/orgs/{orgId}/legal/{kind}/releases/{version}' }],
package/dist/schema.d.ts CHANGED
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/dist/schema.d.ts
3
- size: 38097691 bytes
4
- sha256: 5766328f985213c33fd969f9ec25648ef5617df0e28956ea0f54e33607b7cc82
3
+ size: 38139997 bytes
4
+ sha256: d21df5bd505382f6d334231b67cb49f88475ea397f4f52ad1e118c79f6fd097a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forumulate/sdk",
3
- "version": "0.13.8",
3
+ "version": "0.14.0",
4
4
  "description": "Typed TypeScript client for the Forumulate REST API.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://forumulate.com/reference",