@clowdops/tsclient 0.6.1 → 0.6.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/README.md CHANGED
@@ -1,11 +1,11 @@
1
- # @flashbacktech/tsclient
1
+ # @clowdops/tsclient
2
2
 
3
3
  TypeScript client for the cloud-agent platform API. Speaks the new domain vocabulary (`project` / `sandbox`) regardless of any residual legacy field names on the wire.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```bash
8
- npm install @flashbacktech/tsclient
8
+ npm install @clowdops/tsclient
9
9
  # Optional, only needed if you use the chat SSE helper in a browser
10
10
  npm install event-source-polyfill
11
11
  ```
@@ -13,7 +13,7 @@ npm install event-source-polyfill
13
13
  ## Usage
14
14
 
15
15
  ```ts
16
- import { CloudAgentClient } from '@flashbacktech/tsclient';
16
+ import { CloudAgentClient } from '@clowdops/tsclient';
17
17
 
18
18
  const client = new CloudAgentClient({
19
19
  baseUrl: 'http://localhost:3010',
@@ -45,7 +45,7 @@ stream.close();
45
45
  Every non-2xx response throws an `HttpError`:
46
46
 
47
47
  ```ts
48
- import { HttpError } from '@flashbacktech/tsclient';
48
+ import { HttpError } from '@clowdops/tsclient';
49
49
 
50
50
  try {
51
51
  await client.auth.login({ email, password });
package/dist/index.cjs CHANGED
@@ -85,7 +85,7 @@ var BaseClient = class {
85
85
  }
86
86
  }
87
87
  if (this.debug) {
88
- console.debug("[flashbacktech/tsclient] \u2192", method, url, options.body ?? "");
88
+ console.debug("[clowdops/tsclient] \u2192", method, url, options.body ?? "");
89
89
  }
90
90
  const res = await this.fetchImpl(url, { method, headers, body, credentials: this.credentials });
91
91
  let parsed = null;
@@ -98,7 +98,7 @@ var BaseClient = class {
98
98
  }
99
99
  }
100
100
  if (this.debug) {
101
- console.debug("[flashbacktech/tsclient] \u2190", res.status, url, parsed);
101
+ console.debug("[clowdops/tsclient] \u2190", res.status, url, parsed);
102
102
  }
103
103
  if (!res.ok) {
104
104
  if (res.status === 401 && this.onUnauthorized && !options.skipAuth && !retrying) {
@@ -2913,6 +2913,210 @@ var ConnectionsClient = class {
2913
2913
  }
2914
2914
  };
2915
2915
 
2916
+ // src/modules/connect/types.ts
2917
+ var CONNECT_AUTHORIZE_V1 = "connect.authorize.v1";
2918
+ var CONNECTION_DISCONNECT_V1 = "connection.disconnect.v1";
2919
+ var CONNECT_RESULT_V1 = "connect.result.v1";
2920
+
2921
+ // src/modules/connect/validate.ts
2922
+ var SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS = Object.freeze({
2923
+ MEETING_SOURCE: "v1",
2924
+ CRM: "v1",
2925
+ WORK_TRACKING: "v1",
2926
+ CALENDAR: "v1",
2927
+ EMAIL: "v1",
2928
+ CHANNEL_NOTIFICATION: "v1"
2929
+ });
2930
+ var PROVIDER_LIFECYCLE_SURFACE = "PROVIDER_LIFECYCLE";
2931
+ var SUPPORTED_PROVIDER_LIFECYCLE_SURFACE_VERSION = "v1";
2932
+ var CONNECT_CAPABILITY_DISPLAY_STATES = /* @__PURE__ */ new Set([
2933
+ "supported",
2934
+ "conditional",
2935
+ "degraded",
2936
+ "unavailable",
2937
+ "unknown"
2938
+ ]);
2939
+ var ConnectCatalogValidationError = class extends Error {
2940
+ constructor(message) {
2941
+ super(message);
2942
+ this.name = "ConnectCatalogValidationError";
2943
+ }
2944
+ };
2945
+ function fail(message) {
2946
+ throw new ConnectCatalogValidationError(message);
2947
+ }
2948
+ function isRecord(v) {
2949
+ return typeof v === "object" && v !== null && !Array.isArray(v);
2950
+ }
2951
+ function requireString(obj, key, ctx) {
2952
+ const v = obj[key];
2953
+ if (typeof v !== "string" || v.trim() === "") {
2954
+ fail(`${ctx}: field "${key}" must be a non-empty string`);
2955
+ }
2956
+ return v;
2957
+ }
2958
+ function rejectUnknownKeys(obj, allowed, ctx) {
2959
+ for (const k of Object.keys(obj)) {
2960
+ if (!allowed.includes(k)) fail(`${ctx}: unexpected field "${k}"`);
2961
+ }
2962
+ }
2963
+ var CAPABILITY_STATE_KEYS = [
2964
+ "capability",
2965
+ "surface",
2966
+ "state",
2967
+ "executionLocation",
2968
+ "executionProfile",
2969
+ "condition",
2970
+ "degradation",
2971
+ "spike",
2972
+ "note"
2973
+ ];
2974
+ var CATALOG_ROW_KEYS = [
2975
+ "provider",
2976
+ "displayName",
2977
+ "domains",
2978
+ "domainSurfaceVersions",
2979
+ "providerLifecycleSurfaceVersion",
2980
+ "capabilityStates"
2981
+ ];
2982
+ function validateSurfaceId(surface, ctx) {
2983
+ const at = surface.indexOf("@");
2984
+ if (at <= 0 || at === surface.length - 1) {
2985
+ fail(`${ctx}: surface "${surface}" is not "<SURFACE>@<version>"`);
2986
+ }
2987
+ const name = surface.slice(0, at);
2988
+ const version = surface.slice(at + 1);
2989
+ if (name === PROVIDER_LIFECYCLE_SURFACE) {
2990
+ if (version !== SUPPORTED_PROVIDER_LIFECYCLE_SURFACE_VERSION) {
2991
+ fail(`${ctx}: unsupported PROVIDER_LIFECYCLE surface version "${version}"`);
2992
+ }
2993
+ return;
2994
+ }
2995
+ const supported = SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS[name];
2996
+ if (supported === void 0) fail(`${ctx}: unknown connector surface "${name}"`);
2997
+ if (supported !== version) fail(`${ctx}: unsupported surface version "${version}" for "${name}"`);
2998
+ }
2999
+ function parseCapabilityState(raw, ctx) {
3000
+ if (!isRecord(raw)) fail(`${ctx}: capability state must be an object`);
3001
+ rejectUnknownKeys(raw, CAPABILITY_STATE_KEYS, ctx);
3002
+ const capability = requireString(raw, "capability", ctx);
3003
+ const surface = requireString(raw, "surface", ctx);
3004
+ validateSurfaceId(surface, `${ctx}.surface`);
3005
+ const state = raw.state;
3006
+ if (typeof state !== "string" || !CONNECT_CAPABILITY_DISPLAY_STATES.has(state)) {
3007
+ fail(`${ctx}: unknown capability state "${String(state)}"`);
3008
+ }
3009
+ const out = {
3010
+ capability,
3011
+ surface,
3012
+ state
3013
+ };
3014
+ if (raw.executionLocation !== void 0) {
3015
+ if (raw.executionLocation !== "sandbox" && raw.executionLocation !== "server-side") {
3016
+ fail(`${ctx}: unknown executionLocation "${String(raw.executionLocation)}"`);
3017
+ }
3018
+ out.executionLocation = raw.executionLocation;
3019
+ }
3020
+ for (const opt of ["executionProfile", "condition", "degradation", "spike", "note"]) {
3021
+ if (raw[opt] !== void 0) {
3022
+ if (typeof raw[opt] !== "string") fail(`${ctx}: field "${opt}" must be a string`);
3023
+ out[opt] = raw[opt];
3024
+ }
3025
+ }
3026
+ return out;
3027
+ }
3028
+ function parseConnectCatalogRow(raw) {
3029
+ if (!isRecord(raw)) fail("catalog row must be an object");
3030
+ rejectUnknownKeys(raw, CATALOG_ROW_KEYS, "catalog row");
3031
+ const provider = requireString(raw, "provider", "catalog row");
3032
+ const ctx = `catalog row "${provider}"`;
3033
+ const displayName = requireString(raw, "displayName", ctx);
3034
+ const domains = raw.domains;
3035
+ if (!Array.isArray(domains) || domains.length === 0) {
3036
+ fail(`${ctx}: "domains" must be a non-empty array`);
3037
+ }
3038
+ for (const d of domains) {
3039
+ if (typeof d !== "string") fail(`${ctx}: domain entries must be strings`);
3040
+ if (SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS[d] === void 0) {
3041
+ fail(`${ctx}: unknown connector domain "${d}"`);
3042
+ }
3043
+ }
3044
+ const domainList = domains;
3045
+ const dsv = raw.domainSurfaceVersions;
3046
+ if (!isRecord(dsv)) fail(`${ctx}: "domainSurfaceVersions" must be an object`);
3047
+ for (const d of domainList) {
3048
+ const v = dsv[d];
3049
+ if (typeof v !== "string") fail(`${ctx}: missing surface version for domain "${d}"`);
3050
+ if (SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS[d] !== v) {
3051
+ fail(`${ctx}: unsupported surface version "${v}" for domain "${d}"`);
3052
+ }
3053
+ }
3054
+ for (const k of Object.keys(dsv)) {
3055
+ if (!domainList.includes(k)) fail(`${ctx}: surface version for unlisted domain "${k}"`);
3056
+ }
3057
+ const plsv = requireString(raw, "providerLifecycleSurfaceVersion", ctx);
3058
+ if (plsv !== SUPPORTED_PROVIDER_LIFECYCLE_SURFACE_VERSION) {
3059
+ fail(`${ctx}: unsupported providerLifecycleSurfaceVersion "${plsv}"`);
3060
+ }
3061
+ const capStates = raw.capabilityStates;
3062
+ if (!Array.isArray(capStates)) fail(`${ctx}: "capabilityStates" must be an array`);
3063
+ const capabilityStates = capStates.map((c, i) => parseCapabilityState(c, `${ctx} capabilityStates[${i}]`));
3064
+ return {
3065
+ provider,
3066
+ displayName,
3067
+ domains: domainList,
3068
+ domainSurfaceVersions: { ...dsv },
3069
+ providerLifecycleSurfaceVersion: plsv,
3070
+ capabilityStates
3071
+ };
3072
+ }
3073
+ function parseConnectCatalog(raw) {
3074
+ if (!Array.isArray(raw)) fail("connect catalog must be an array");
3075
+ return raw.map((r) => parseConnectCatalogRow(r));
3076
+ }
3077
+ var RESULT_STATUSES = /* @__PURE__ */ new Set(["connected", "orphan_grant", "failed"]);
3078
+ function parseConnectResultV1(raw) {
3079
+ if (!isRecord(raw)) fail("connect result must be an object");
3080
+ if (raw.contractVersion !== CONNECT_RESULT_V1) {
3081
+ fail(`connect result: unsupported contractVersion "${String(raw.contractVersion)}"`);
3082
+ }
3083
+ const status = raw.status;
3084
+ if (typeof status !== "string" || !RESULT_STATUSES.has(status)) {
3085
+ fail(`connect result: unknown status "${String(status)}"`);
3086
+ }
3087
+ const resultId = requireString(raw, "resultId", "connect result");
3088
+ const provider = requireString(raw, "provider", "connect result");
3089
+ if (status === "connected") {
3090
+ const connectionId = requireString(raw, "connectionId", "connect result");
3091
+ const granted = raw.grantedCapabilities;
3092
+ if (!Array.isArray(granted) || granted.some((g) => typeof g !== "string")) {
3093
+ fail('connect result: "grantedCapabilities" must be a string array');
3094
+ }
3095
+ const out = {
3096
+ contractVersion: CONNECT_RESULT_V1,
3097
+ status: "connected",
3098
+ resultId,
3099
+ provider,
3100
+ connectionId,
3101
+ grantedCapabilities: granted
3102
+ };
3103
+ if (raw.accountLabel !== void 0) {
3104
+ if (typeof raw.accountLabel !== "string") fail("connect result: accountLabel must be a string");
3105
+ out.accountLabel = raw.accountLabel;
3106
+ }
3107
+ if (raw.tenantLabel !== void 0) {
3108
+ if (typeof raw.tenantLabel !== "string") fail("connect result: tenantLabel must be a string");
3109
+ out.tenantLabel = raw.tenantLabel;
3110
+ }
3111
+ return out;
3112
+ }
3113
+ if (status === "orphan_grant") {
3114
+ return { contractVersion: CONNECT_RESULT_V1, status: "orphan_grant", resultId, provider };
3115
+ }
3116
+ const failureClass = requireString(raw, "failureClass", "connect result");
3117
+ return { contractVersion: CONNECT_RESULT_V1, status: "failed", resultId, provider, failureClass };
3118
+ }
3119
+
2916
3120
  // src/modules/connect/ConnectClient.ts
2917
3121
  var ConnectClient = class {
2918
3122
  constructor(http) {
@@ -2970,16 +3174,107 @@ var ConnectClient = class {
2970
3174
  return res.connection;
2971
3175
  }
2972
3176
  /**
2973
- * disconnect revokes a delegated grant by deleting the project credential
2974
- * that backs it (`DELETE /credentials/<id>`), the existing project
2975
- * credential-delete surface (proposal §5.1, C2-BE-OAUTH-LIFECYCLE). The
2976
- * redacted envelope carries no secret.
3177
+ * @deprecated Legacy LOCAL credential delete — kept operational for the BI
3178
+ * connect surface. It performs `DELETE /credentials/<id>`, which erases the
3179
+ * local project credential; it does NOT contact the provider and is NOT an
3180
+ * upstream revoke. Do not present its result as "revoked". For the
3181
+ * product-neutral Meeting rail use {@link ConnectClient.disconnectV1}, which
3182
+ * disables local use, advances the connection epoch and returns the honest
3183
+ * remote outcome. The redacted envelope carries no secret.
2977
3184
  */
2978
3185
  disconnect(input) {
2979
3186
  return this.http.delete(
2980
3187
  `/credentials/${encodeURIComponent(input.credentialId)}`
2981
3188
  );
2982
3189
  }
3190
+ // ─────────────────────────────────────────────────────────────────────────
3191
+ // MTG-S01-PROVIDER-RAIL@v3 — product-neutral v1 connect wire.
3192
+ // ─────────────────────────────────────────────────────────────────────────
3193
+ /**
3194
+ * getCatalogV1 fetches the redacted connect catalog for a product
3195
+ * (`GET /connect/catalog?product=`). Each row carries connector-domain
3196
+ * memberships, versioned surface identities and a complete capability-state
3197
+ * matrix; the panel groups/filters from this projection and never from a
3198
+ * client-side allowlist. A contained family is absent from the catalog. The
3199
+ * returned rows carry no credential material.
3200
+ */
3201
+ async getCatalogV1(product) {
3202
+ const res = await this.http.get(
3203
+ "/connect/catalog",
3204
+ { query: { product } }
3205
+ );
3206
+ if (res.providers === void 0 || res.providers === null) return [];
3207
+ return parseConnectCatalog(res.providers);
3208
+ }
3209
+ /**
3210
+ * authorizeStartV1 begins the product-neutral authorization-code flow
3211
+ * (`POST /connect/authorizations`, contract connect.authorize.v1). The client
3212
+ * sends only the active product/project/sandbox scope, the provider and the
3213
+ * requested SEMANTIC capabilities — never a scope string, credential id or
3214
+ * OAuth state. The server authorizes the editor + Team binding, expands the
3215
+ * capabilities to a server-owned scope ceiling, mints an opaque one-use state,
3216
+ * and returns only the authorization URL and its expiry.
3217
+ */
3218
+ async authorizeStartV1(input) {
3219
+ const res = await this.http.post("/connect/authorizations", {
3220
+ body: {
3221
+ contractVersion: CONNECT_AUTHORIZE_V1,
3222
+ product: input.product,
3223
+ projectId: input.projectId,
3224
+ sandboxId: input.sandboxId,
3225
+ provider: input.provider,
3226
+ requestedCapabilities: input.requestedCapabilities
3227
+ }
3228
+ });
3229
+ if (!res.authorizationUrl || !res.expiresAt) {
3230
+ throw new Error("authorizeStartV1 response missing authorizationUrl/expiresAt.");
3231
+ }
3232
+ return {
3233
+ contractVersion: CONNECT_AUTHORIZE_V1,
3234
+ authorizationUrl: res.authorizationUrl,
3235
+ expiresAt: res.expiresAt
3236
+ };
3237
+ }
3238
+ /**
3239
+ * getConnectResultV1 reads back the redacted, bound result of a completed
3240
+ * authorization by its opaque resultId (`GET /connect/results/<resultId>`).
3241
+ * The result is scoped to the bound user/project/Team; query text is never
3242
+ * treated as success authority. The read is idempotent within the bound
3243
+ * session so a React double-fetch does not consume it twice.
3244
+ */
3245
+ async getConnectResultV1(resultId) {
3246
+ const res = await this.http.get(
3247
+ `/connect/results/${encodeURIComponent(resultId)}`
3248
+ );
3249
+ if (res.result === void 0 || res.result === null) {
3250
+ throw new Error("getConnectResultV1 response missing result.");
3251
+ }
3252
+ return parseConnectResultV1(res.result);
3253
+ }
3254
+ /**
3255
+ * disconnectV1 disconnects a connection over the product-neutral rail
3256
+ * (`POST /connections/<id>/disconnect`, contract connection.disconnect.v1).
3257
+ * The client generates the idempotency key; the server disables local use and
3258
+ * advances the epoch BEFORE any remote action, then returns the honest remote
3259
+ * outcome. A repeated call with the same key returns the same terminal
3260
+ * projection and performs no second revoke. Local deletion is never relabelled
3261
+ * as upstream revoke.
3262
+ */
3263
+ async disconnectV1(input) {
3264
+ const res = await this.http.post(`/connections/${encodeURIComponent(input.connectionId)}/disconnect`, {
3265
+ body: { contractVersion: CONNECTION_DISCONNECT_V1 },
3266
+ headers: { "Idempotency-Key": input.idempotencyKey }
3267
+ });
3268
+ if (!res.connectionId || !res.remoteOutcome || res.localState !== "disconnected") {
3269
+ throw new Error("disconnectV1 response missing required fields.");
3270
+ }
3271
+ return {
3272
+ contractVersion: CONNECTION_DISCONNECT_V1,
3273
+ connectionId: res.connectionId,
3274
+ localState: "disconnected",
3275
+ remoteOutcome: res.remoteOutcome
3276
+ };
3277
+ }
2983
3278
  };
2984
3279
 
2985
3280
  // src/modules/capabilities/CapabilitiesClient.ts
@@ -5469,7 +5764,7 @@ function isKnownChatCardType(t) {
5469
5764
  function isKnownChatCardAction(a) {
5470
5765
  return typeof a === "string" && CARD_ACTION_SET.has(a);
5471
5766
  }
5472
- function isRecord(v) {
5767
+ function isRecord2(v) {
5473
5768
  return typeof v === "object" && v !== null && !Array.isArray(v);
5474
5769
  }
5475
5770
  function asString(v) {
@@ -5479,7 +5774,7 @@ function optString(v) {
5479
5774
  return typeof v === "string" && v !== "" ? v : void 0;
5480
5775
  }
5481
5776
  function parseDurableRef(v) {
5482
- if (!isRecord(v)) return void 0;
5777
+ if (!isRecord2(v)) return void 0;
5483
5778
  const kind = asString(v.kind);
5484
5779
  const id = asString(v.id);
5485
5780
  if (kind === "" && id === "") return void 0;
@@ -5502,7 +5797,7 @@ function coerceVersion(v) {
5502
5797
  return void 0;
5503
5798
  }
5504
5799
  function parseChatCard(metadata) {
5505
- if (!isRecord(metadata)) return void 0;
5800
+ if (!isRecord2(metadata)) return void 0;
5506
5801
  const cardType = metadata.card_type;
5507
5802
  if (typeof cardType !== "string" || cardType === "") return void 0;
5508
5803
  const version = coerceVersion(metadata.schema_version);
@@ -6387,9 +6682,14 @@ exports.CHAT_SCHEDULE_RUN_STATUSES = CHAT_SCHEDULE_RUN_STATUSES;
6387
6682
  exports.CHAT_SCHEDULE_RUN_STATUS_IS_FAILURE = CHAT_SCHEDULE_RUN_STATUS_IS_FAILURE;
6388
6683
  exports.CLAIM_ANNOTATIONS_METADATA_KEY = CLAIM_ANNOTATIONS_METADATA_KEY;
6389
6684
  exports.COMPONENT_IDS = COMPONENT_IDS;
6685
+ exports.CONNECTION_DISCONNECT_V1 = CONNECTION_DISCONNECT_V1;
6686
+ exports.CONNECT_AUTHORIZE_V1 = CONNECT_AUTHORIZE_V1;
6687
+ exports.CONNECT_CAPABILITY_DISPLAY_STATES = CONNECT_CAPABILITY_DISPLAY_STATES;
6688
+ exports.CONNECT_RESULT_V1 = CONNECT_RESULT_V1;
6390
6689
  exports.CapabilitiesClient = CapabilitiesClient;
6391
6690
  exports.CapacityClient = CapacityClient;
6392
6691
  exports.CloudAgentClient = CloudAgentClient;
6692
+ exports.ConnectCatalogValidationError = ConnectCatalogValidationError;
6393
6693
  exports.ConnectClient = ConnectClient;
6394
6694
  exports.ConnectionsClient = ConnectionsClient;
6395
6695
  exports.ContactsClient = ContactsClient;
@@ -6411,6 +6711,7 @@ exports.PM_RECIPIENT_NOT_REGISTERED = PM_RECIPIENT_NOT_REGISTERED;
6411
6711
  exports.PM_RECORD_FAMILIES = PM_RECORD_FAMILIES;
6412
6712
  exports.PRODUCT_KINDS = PRODUCT_KINDS;
6413
6713
  exports.PROVIDER_CATALOG = PROVIDER_CATALOG;
6714
+ exports.PROVIDER_LIFECYCLE_SURFACE = PROVIDER_LIFECYCLE_SURFACE;
6414
6715
  exports.PacksClient = PacksClient;
6415
6716
  exports.PersonExportClient = PersonExportClient;
6416
6717
  exports.PlatformAdminClient = PlatformAdminClient;
@@ -6418,6 +6719,8 @@ exports.ProviderType = ProviderType;
6418
6719
  exports.ReferralsClient = ReferralsClient;
6419
6720
  exports.ResellerClient = ResellerClient;
6420
6721
  exports.ResourcesClient = ResourcesClient;
6722
+ exports.SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS = SUPPORTED_CONNECTOR_DOMAIN_SURFACE_VERSIONS;
6723
+ exports.SUPPORTED_PROVIDER_LIFECYCLE_SURFACE_VERSION = SUPPORTED_PROVIDER_LIFECYCLE_SURFACE_VERSION;
6421
6724
  exports.SignalsClient = SignalsClient;
6422
6725
  exports.TelegramClient = TelegramClient;
6423
6726
  exports.biVerificationOf = biVerificationOf;
@@ -6458,6 +6761,9 @@ exports.meetingRoleAffordances = meetingRoleAffordances;
6458
6761
  exports.metadataKey = metadataKey;
6459
6762
  exports.newProjectRequestKey = newProjectRequestKey;
6460
6763
  exports.parseChatCard = parseChatCard;
6764
+ exports.parseConnectCatalog = parseConnectCatalog;
6765
+ exports.parseConnectCatalogRow = parseConnectCatalogRow;
6766
+ exports.parseConnectResultV1 = parseConnectResultV1;
6461
6767
  exports.parsePmDocumentCitation = parsePmDocumentCitation;
6462
6768
  exports.personExportIsEmpty = personExportIsEmpty;
6463
6769
  exports.personExportIsLimited = personExportIsLimited;