@yadsh/dsh-qa-integrations 0.6.0 → 0.8.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.
Files changed (183) hide show
  1. package/README.md +341 -303
  2. package/lib/broker.js +12 -0
  3. package/lib/broker.js.map +1 -1
  4. package/lib/client/bitrix24.js +66 -5
  5. package/lib/client/bitrix24.js.map +1 -1
  6. package/lib/client/confluence.js +117 -128
  7. package/lib/client/confluence.js.map +1 -1
  8. package/lib/client/gitlab.js +1 -1
  9. package/lib/client/gitlab.js.map +1 -1
  10. package/lib/client/index.js +25 -5
  11. package/lib/client/index.js.map +1 -1
  12. package/lib/client/integrations.js +1 -1
  13. package/lib/client/integrations.js.map +1 -1
  14. package/lib/client/jira.js +115 -126
  15. package/lib/client/jira.js.map +1 -1
  16. package/lib/client/operator-card.js +537 -0
  17. package/lib/client/operator-card.js.map +1 -0
  18. package/lib/client/operator-controls.js +232 -0
  19. package/lib/client/operator-controls.js.map +1 -0
  20. package/lib/client/styles.js +60 -0
  21. package/lib/client/styles.js.map +1 -1
  22. package/lib/client/testit.js +39 -3
  23. package/lib/client/testit.js.map +1 -1
  24. package/lib/client/weblate.js +38 -3
  25. package/lib/client/weblate.js.map +1 -1
  26. package/lib/client.js +2966 -871
  27. package/lib/client.js.map +1 -1
  28. package/lib/coerce.js +17 -1
  29. package/lib/coerce.js.map +1 -1
  30. package/lib/config.js.map +1 -1
  31. package/lib/errors.js +22 -0
  32. package/lib/errors.js.map +1 -1
  33. package/lib/index.js +211 -52
  34. package/lib/index.js.map +1 -1
  35. package/lib/providers/bitrix24/catalog.js +138 -8
  36. package/lib/providers/bitrix24/catalog.js.map +1 -1
  37. package/lib/providers/bitrix24/config.js +84 -14
  38. package/lib/providers/bitrix24/config.js.map +1 -1
  39. package/lib/providers/bitrix24/index.js +100 -0
  40. package/lib/providers/bitrix24/index.js.map +1 -1
  41. package/lib/providers/bitrix24/operations.js +5 -9
  42. package/lib/providers/bitrix24/operations.js.map +1 -1
  43. package/lib/providers/bitrix24/transport.js +11 -31
  44. package/lib/providers/bitrix24/transport.js.map +1 -1
  45. package/lib/providers/confluence/adf.js +28 -23
  46. package/lib/providers/confluence/adf.js.map +1 -1
  47. package/lib/providers/confluence/catalog.js +91 -7
  48. package/lib/providers/confluence/catalog.js.map +1 -1
  49. package/lib/providers/confluence/config.js +27 -2
  50. package/lib/providers/confluence/config.js.map +1 -1
  51. package/lib/providers/confluence/credential-help.js +14 -8
  52. package/lib/providers/confluence/credential-help.js.map +1 -1
  53. package/lib/providers/confluence/dialect.js +215 -0
  54. package/lib/providers/confluence/dialect.js.map +1 -0
  55. package/lib/providers/confluence/index.js +393 -79
  56. package/lib/providers/confluence/index.js.map +1 -1
  57. package/lib/providers/confluence/operations.js +208 -153
  58. package/lib/providers/confluence/operations.js.map +1 -1
  59. package/lib/providers/confluence/storage.js +690 -0
  60. package/lib/providers/confluence/storage.js.map +1 -0
  61. package/lib/providers/confluence/transport.js +26 -89
  62. package/lib/providers/confluence/transport.js.map +1 -1
  63. package/lib/providers/gitlab/config.js +2 -3
  64. package/lib/providers/gitlab/config.js.map +1 -1
  65. package/lib/providers/gitlab/index.js +2 -20
  66. package/lib/providers/gitlab/index.js.map +1 -1
  67. package/lib/providers/gitlab/operations.js +7 -45
  68. package/lib/providers/gitlab/operations.js.map +1 -1
  69. package/lib/providers/gitlab/transport.js +2 -18
  70. package/lib/providers/gitlab/transport.js.map +1 -1
  71. package/lib/providers/jira/adf.js +19 -14
  72. package/lib/providers/jira/adf.js.map +1 -1
  73. package/lib/providers/jira/catalog.js +125 -4
  74. package/lib/providers/jira/catalog.js.map +1 -1
  75. package/lib/providers/jira/config.js +27 -2
  76. package/lib/providers/jira/config.js.map +1 -1
  77. package/lib/providers/jira/credential-help.js +16 -7
  78. package/lib/providers/jira/credential-help.js.map +1 -1
  79. package/lib/providers/jira/dialect.js +94 -0
  80. package/lib/providers/jira/dialect.js.map +1 -0
  81. package/lib/providers/jira/index.js +327 -67
  82. package/lib/providers/jira/index.js.map +1 -1
  83. package/lib/providers/jira/jql.js +54 -21
  84. package/lib/providers/jira/jql.js.map +1 -1
  85. package/lib/providers/jira/operations.js +77 -55
  86. package/lib/providers/jira/operations.js.map +1 -1
  87. package/lib/providers/jira/tools.js +1 -1
  88. package/lib/providers/jira/tools.js.map +1 -1
  89. package/lib/providers/jira/transport.js +12 -83
  90. package/lib/providers/jira/transport.js.map +1 -1
  91. package/lib/providers/shared/health.js +31 -0
  92. package/lib/providers/shared/health.js.map +1 -0
  93. package/lib/providers/shared/http.js +20 -0
  94. package/lib/providers/shared/http.js.map +1 -1
  95. package/lib/providers/shared/paths.js +14 -0
  96. package/lib/providers/shared/paths.js.map +1 -0
  97. package/lib/providers/shared/payload.js +46 -0
  98. package/lib/providers/shared/payload.js.map +1 -0
  99. package/lib/providers/teamcity/artifacts.js +0 -8
  100. package/lib/providers/teamcity/artifacts.js.map +1 -1
  101. package/lib/providers/teamcity/config.js +2 -3
  102. package/lib/providers/teamcity/config.js.map +1 -1
  103. package/lib/providers/teamcity/index.js +2 -20
  104. package/lib/providers/teamcity/index.js.map +1 -1
  105. package/lib/providers/teamcity/operations.js +5 -39
  106. package/lib/providers/teamcity/operations.js.map +1 -1
  107. package/lib/providers/teamcity/transport.js +2 -11
  108. package/lib/providers/teamcity/transport.js.map +1 -1
  109. package/lib/providers/testit/catalog.js +77 -0
  110. package/lib/providers/testit/catalog.js.map +1 -1
  111. package/lib/providers/testit/config.js +2 -3
  112. package/lib/providers/testit/config.js.map +1 -1
  113. package/lib/providers/testit/index.js +260 -4
  114. package/lib/providers/testit/index.js.map +1 -1
  115. package/lib/providers/testit/operations.js +34 -63
  116. package/lib/providers/testit/operations.js.map +1 -1
  117. package/lib/providers/testit/transport.js +2 -18
  118. package/lib/providers/testit/transport.js.map +1 -1
  119. package/lib/providers/weblate/catalog.js +103 -9
  120. package/lib/providers/weblate/catalog.js.map +1 -1
  121. package/lib/providers/weblate/config.js +2 -3
  122. package/lib/providers/weblate/config.js.map +1 -1
  123. package/lib/providers/weblate/index.js +227 -6
  124. package/lib/providers/weblate/index.js.map +1 -1
  125. package/lib/providers/weblate/operations.js +3 -33
  126. package/lib/providers/weblate/operations.js.map +1 -1
  127. package/lib/providers/weblate/query.js +3 -6
  128. package/lib/providers/weblate/query.js.map +1 -1
  129. package/lib/providers/weblate/transport.js +2 -12
  130. package/lib/providers/weblate/transport.js.map +1 -1
  131. package/lib/service-credentials/config.js +2 -3
  132. package/lib/service-credentials/config.js.map +1 -1
  133. package/lib/shared/settings.js +14 -0
  134. package/lib/shared/settings.js.map +1 -0
  135. package/lib/typert.host.js +159 -60
  136. package/lib/typert.remote-client.d.ts +13 -11
  137. package/lib/typert.remote-client.js +98 -52
  138. package/lib/types/broker.d.ts +11 -3
  139. package/lib/types/client/bitrix24.d.ts +24 -2
  140. package/lib/types/client/confluence.d.ts +24 -4
  141. package/lib/types/client/index.d.ts +7 -6
  142. package/lib/types/client/integrations.d.ts +2 -2
  143. package/lib/types/client/jira.d.ts +25 -4
  144. package/lib/types/client/operator-card.d.ts +22 -0
  145. package/lib/types/client/operator-controls.d.ts +135 -0
  146. package/lib/types/client/testit.d.ts +14 -1
  147. package/lib/types/client/weblate.d.ts +14 -1
  148. package/lib/types/coerce.d.ts +14 -0
  149. package/lib/types/config.d.ts +4 -4
  150. package/lib/types/errors.d.ts +16 -0
  151. package/lib/types/index.d.ts +91 -15
  152. package/lib/types/providers/bitrix24/catalog.d.ts +8 -0
  153. package/lib/types/providers/bitrix24/config.d.ts +14 -23
  154. package/lib/types/providers/bitrix24/index.d.ts +37 -1
  155. package/lib/types/providers/confluence/catalog.d.ts +44 -8
  156. package/lib/types/providers/confluence/config.d.ts +39 -7
  157. package/lib/types/providers/confluence/credential-help.d.ts +9 -4
  158. package/lib/types/providers/confluence/dialect.d.ts +113 -0
  159. package/lib/types/providers/confluence/index.d.ts +82 -8
  160. package/lib/types/providers/confluence/operations.d.ts +14 -4
  161. package/lib/types/providers/confluence/storage.d.ts +28 -0
  162. package/lib/types/providers/confluence/transport.d.ts +10 -21
  163. package/lib/types/providers/jira/catalog.d.ts +49 -2
  164. package/lib/types/providers/jira/config.d.ts +37 -6
  165. package/lib/types/providers/jira/credential-help.d.ts +11 -3
  166. package/lib/types/providers/jira/dialect.d.ts +79 -0
  167. package/lib/types/providers/jira/index.d.ts +76 -19
  168. package/lib/types/providers/jira/jql.d.ts +14 -4
  169. package/lib/types/providers/jira/operations.d.ts +3 -0
  170. package/lib/types/providers/jira/transport.d.ts +6 -13
  171. package/lib/types/providers/shared/health.d.ts +18 -0
  172. package/lib/types/providers/shared/http.d.ts +9 -0
  173. package/lib/types/providers/shared/paths.d.ts +10 -0
  174. package/lib/types/providers/shared/payload.d.ts +26 -0
  175. package/lib/types/providers/teamcity/artifacts.d.ts +0 -2
  176. package/lib/types/providers/teamcity/index.d.ts +2 -0
  177. package/lib/types/providers/testit/catalog.d.ts +12 -0
  178. package/lib/types/providers/testit/index.d.ts +63 -2
  179. package/lib/types/providers/weblate/catalog.d.ts +19 -2
  180. package/lib/types/providers/weblate/index.d.ts +43 -1
  181. package/lib/types/shared/settings.d.ts +14 -0
  182. package/lib/types/types.d.ts +8 -0
  183. package/package.json +3 -3
@@ -1,9 +1,26 @@
1
1
  import { type CredentialHelp } from "@yadsh/dsh-plugin-kit";
2
2
  import type { ResolvedQaIntegrationsConfig } from "../../config.js";
3
- import type { IntegrationCapability, IntegrationCapabilityInfo, ProviderValidation } from "../../types.js";
3
+ import type { OperationSecurityMetadata, ServiceCredentialHealth, ServiceResourceBoundary } from "../../service-credentials/types.js";
4
+ import type { CapabilityServiceState, IntegrationCapability, IntegrationCapabilityInfo, ProviderValidation } from "../../types.js";
4
5
  import type { IntegrationProvider, ProviderContext } from "../contract.js";
5
6
  export { credentialFromPlaintext, credentialInstance, type ConfluenceCredential, } from "./transport.js";
6
- /** Confluence provider: operator-configured sites over an Atlassian API token. */
7
+ /**
8
+ * Whether one space key stays inside the deployment's boundary. The profile's
9
+ * `resources.spaces` lists space keys — the same vocabulary the deployment's
10
+ * own allowlist and the CQL speak — and keys are compared case-insensitively,
11
+ * because operator config, the v2 API and CQL spell the same key in different
12
+ * cases.
13
+ */
14
+ export declare function spaceInBoundary(boundary: ServiceResourceBoundary, key: string | undefined): boolean;
15
+ /**
16
+ * Confluence provider: operator-configured sites over an Atlassian API token
17
+ * (Cloud) or a personal access token (Server / Data Center).
18
+ *
19
+ * Which product answers at a site — and so which endpoints, which
20
+ * authentication scheme and which shape of body this provider speaks — is the
21
+ * site's own declared deployment type, never a guess made at connect or at run
22
+ * time.
23
+ */
7
24
  export declare class ConfluenceProvider implements IntegrationProvider {
8
25
  private readonly config;
9
26
  readonly id = "confluence";
@@ -28,20 +45,45 @@ export declare class ConfluenceProvider implements IntegrationProvider {
28
45
  * from operator config, never from a tool argument, which is what keeps the
29
46
  * broker from dialling any host the caller names or authenticating as any
30
47
  * account the caller names.
48
+ *
49
+ * A deployment-managed secret cannot travel with a connect form, so on Cloud
50
+ * it arrives as the Basic pair Atlassian documents (`email:token`); the two
51
+ * forms can never be confused there, because an API token contains neither
52
+ * `@` nor `:`. A Server / Data Center personal access token is the secret
53
+ * alone, and its connection stores an empty e-mail: the instance's declared
54
+ * deployment type is what decides whether an account is required.
31
55
  */
32
56
  parseCredential(raw: string, options?: Readonly<Record<string, string>>): {
33
57
  readonly credential: string;
34
58
  readonly portal: string;
35
59
  };
36
60
  operationCapability(operation: string): IntegrationCapability | undefined;
61
+ operationMetadata(operation: string): OperationSecurityMetadata | undefined;
62
+ /** Every space-scoped read is bounded by the profile's space keys. */
63
+ resourceBoundaryKind(operation: string): string | undefined;
64
+ /**
65
+ * Portal of a configured site. An empty id means "the only site", the same
66
+ * rule `parseCredential` applies, so deployment configuration and the
67
+ * connect form name sites alike.
68
+ */
69
+ instancePortal(instanceId: string): string | undefined;
70
+ capabilityServiceState(capability: IntegrationCapability): CapabilityServiceState | undefined;
37
71
  validate(context: ProviderContext): Promise<ProviderValidation>;
72
+ /**
73
+ * Health of a deployment-managed token. The probe reads only the identity
74
+ * endpoint the personal validation reads, so it never changes upstream state;
75
+ * Confluence exposes no token-scope introspection, so the answer is healthy
76
+ * with a warning — the local service ceiling stays the whole local boundary.
77
+ */
78
+ validateServiceCredential(context: ProviderContext): Promise<ServiceCredentialHealth>;
38
79
  execute(context: ProviderContext, operation: string, input: Readonly<Record<string, unknown>>): Promise<unknown>;
39
80
  /** One list read, with its cursor and with the space policy re-applied. */
40
81
  private readList;
41
82
  /**
42
83
  * A page read is answered with the page's space, because that is what the
43
84
  * operator allowlist is written in — and a page whose space the policy does
44
- * not allow is refused here, after the read and before the model sees it.
85
+ * not allow is refused here, after the read and before the model sees it. In
86
+ * service mode the boundary is verified on the same resolved space.
45
87
  */
46
88
  private readPage;
47
89
  /**
@@ -55,14 +97,44 @@ export declare class ConfluenceProvider implements IntegrationProvider {
55
97
  private withReplies;
56
98
  /** One space, by id or by the key the listing endpoint resolves. */
57
99
  private readSpace;
100
+ /**
101
+ * A service search is narrowed to the boundary before the handler builds the
102
+ * CQL: an offset-paginated search whose out-of-boundary rows were dropped
103
+ * afterwards would answer pages that shrink and cursors that lose their
104
+ * place. A space the caller names outside the boundary is refused rather
105
+ * than dropped, and the filter in `readList` stays as the second lock.
106
+ */
107
+ private boundedSearchInput;
108
+ /**
109
+ * The bounded space listing. A service profile names the spaces it covers,
110
+ * so the listing is built from that list instead of from whatever the shared
111
+ * account can reach; a space the service token cannot see is reported as
112
+ * unavailable rather than silently dropped. The answer does not page: its
113
+ * size is the boundary the administrator defined, not upstream's.
114
+ */
115
+ private listBoundedSpaces;
58
116
  /** The fields a space contributes to a page answer, plus its policy key. */
59
117
  private readSpaceFields;
60
118
  /**
61
- * The space of a page the call is about. Only asked for when the deployment
62
- * narrowed spaces: without an allowlist there is no policy to enforce, and
63
- * the extra read would be spent for nothing.
119
+ * The space a page belongs to, as the product reports it. Cloud names the
120
+ * space by an id on the page, so it is resolved with a second read; a
121
+ * Server / Data Center installation carries the space itself on the page, and
122
+ * that read would be spent for nothing.
123
+ */
124
+ private spaceOfPage;
125
+ /**
126
+ * The space of a page the call is about. Asked for whenever a policy needs
127
+ * it: the deployment allowlist, or — in service mode — the boundary, which is
128
+ * always there. Without either there is no policy to enforce, and the extra
129
+ * reads would be spent for nothing.
130
+ */
131
+ private assertPageReachable;
132
+ /**
133
+ * Both space policies of one read, in the order a refusal should name them:
134
+ * the deployment allowlist first, the service boundary — when the call runs
135
+ * on the managed credential — second.
64
136
  */
65
- private assertPageAllowedBySpace;
137
+ private assertSpaceReachable;
66
138
  /**
67
139
  * A space outside the operator allowlist is refused as a policy decision, not
68
140
  * as a Confluence permission: the account may well be allowed to read it, and
@@ -70,9 +142,11 @@ export declare class ConfluenceProvider implements IntegrationProvider {
70
142
  */
71
143
  private assertSpaceAllowed;
72
144
  /** The space of one search row, as the projection resolved it. */
73
- private itemSpaceAllowed;
145
+ private itemSpaceReachable;
74
146
  private projectionContext;
75
147
  private resolveInstance;
76
148
  }
149
+ /** A missing or forbidden space inside a boundary is reported, not fatal. */
150
+ /** Map an upstream failure of the probe onto a health status. */
77
151
  export default ConfluenceProvider;
78
152
  //# sourceMappingURL=index.d.ts.map
@@ -1,5 +1,5 @@
1
1
  import type { ConfluenceInstance, ConfluenceFlags } from "./config.js";
2
- import type { ConfluenceQuery } from "./transport.js";
2
+ import type { ConfluenceDialect, ConfluenceQuery } from "./dialect.js";
3
3
  /** Rows one answer asks for when the model names no `limit`. */
4
4
  export declare const DEFAULT_LIMIT = 20;
5
5
  /** A page or comment id, accepted as a number or as its decimal digits. */
@@ -8,6 +8,8 @@ export declare function numericId(value: unknown, field: string): string;
8
8
  export declare function spaceRef(value: unknown, field?: string): string;
9
9
  /** Whether a space reference is the numeric id v2 wants in a path. */
10
10
  export declare function isNumericSpace(value: string): boolean;
11
+ /** Space keys the model named, upper-cased the way CQL and the policy spell them. */
12
+ export declare function spaceKeys(value: unknown, field: string): string[];
11
13
  /**
12
14
  * Rows per answer. A `limit` above the deployment cap is clamped rather than
13
15
  * refused: the answer says how many rows it carries, so the model can page on
@@ -23,6 +25,12 @@ export declare function bodyLimit(value: unknown, flags: ConfluenceFlags): numbe
23
25
  * another user's data.
24
26
  */
25
27
  export declare function offsetCursor(value: unknown): number;
28
+ /**
29
+ * v2 pagination is cursor-based and a v1 listing is offset-based, so the shape
30
+ * of a continuation token depends on the product that issued it. Both are
31
+ * shape-checked before they are spent, and neither is ever a URL.
32
+ */
33
+ export declare function listingCursor(value: unknown, dialect: ConfluenceDialect): string | undefined;
26
34
  /** v2 pagination is cursor-based; the token is shape-checked before it is spent. */
27
35
  export declare function upstreamCursor(value: unknown): string | undefined;
28
36
  /**
@@ -37,10 +45,10 @@ export type ConfluenceCommentKind = (typeof COMMENT_KINDS)[number];
37
45
  export declare function commentKind(value: unknown): ConfluenceCommentKind;
38
46
  /** Collections a kind reads; `all` is the two of them, in this order. */
39
47
  export declare function commentCollections(kind: ConfluenceCommentKind): readonly ("footer" | "inline")[];
40
- /** The page-relative collection path of one comment kind. */
41
- export declare function commentPath(pageId: string, kind: "footer" | "inline"): string;
48
+ /** The page-relative collection path of one comment kind, on this product. */
49
+ export declare function commentPath(dialect: ConfluenceDialect, pageId: string, kind: "footer" | "inline", cursor: string | undefined, limit: number): ConfluenceRequest;
42
50
  /** The replies of one comment; the collection decides which endpoint owns them. */
43
- export declare function commentChildrenPath(kind: "footer" | "inline", commentId: string): string;
51
+ export declare function commentChildrenPath(dialect: ConfluenceDialect, kind: "footer" | "inline", commentId: string, cursor: string | undefined, limit: number): ConfluenceRequest;
44
52
  export declare const SPACE_TYPES: readonly string[];
45
53
  export interface OperationContext {
46
54
  /**
@@ -51,6 +59,8 @@ export interface OperationContext {
51
59
  */
52
60
  readonly externalUserId?: string | undefined;
53
61
  readonly flags: ConfluenceFlags;
62
+ /** The product this instance is, which decides endpoints and paging. */
63
+ readonly dialect: ConfluenceDialect;
54
64
  }
55
65
  export interface ConfluenceRequest {
56
66
  readonly path: string;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Confluence Server and Data Center answer a page body as storage format: the
3
+ * XHTML-ish markup the editor keeps under a page, returned in
4
+ * `body.storage.value`. Its Cloud counterpart is Atlassian Document Format,
5
+ * which `adf.ts` renders; this module is the same trade for the self-hosted
6
+ * product, so a caller reads a page's words instead of the wrappers around
7
+ * them.
8
+ *
9
+ * The flattening is as defensive as the other renderers here, and for the same
10
+ * reason: a body is untrusted text a reader asked for, not instructions to
11
+ * follow. Nothing is fetched, executed or followed — a macro becomes a
12
+ * placeholder line, a reference becomes a marker, and a macro's parameters,
13
+ * which hold arbitrary page-authored text, are dropped except for the one that
14
+ * names a code language. A body that is hostile (unbalanced, nested past all
15
+ * reason, full of control characters) is still only read.
16
+ *
17
+ * Rendering is a scan and a small tree of kept tags, not a DOM: the body is
18
+ * walked once by index, so a megabyte of markup costs one pass, and the depth
19
+ * ceiling bounds both what the tree can hold and what the renderer will walk.
20
+ */
21
+ /** Whether a value looks like a storage body rather than a plain string. */
22
+ export declare function isStorage(value: unknown): boolean;
23
+ /**
24
+ * Render one storage-format body to markdown-like text, or "" when there is
25
+ * nothing to render.
26
+ */
27
+ export declare function storageToText(value: unknown): string;
28
+ //# sourceMappingURL=storage.d.ts.map
@@ -1,5 +1,7 @@
1
1
  import type { ResolvedQaIntegrationsConfig } from "../../config.js";
2
2
  import { type ConfluenceFlags, type ConfluenceInstance } from "./config.js";
3
+ import { type ConfluenceQuery } from "./dialect.js";
4
+ export type { ConfluenceQuery } from "./dialect.js";
3
5
  /**
4
6
  * Encrypted credential payload of one Confluence connection: which configured
5
7
  * site it belongs to, the Atlassian account e-mail and the API token. The base
@@ -10,7 +12,10 @@ import { type ConfluenceFlags, type ConfluenceInstance } from "./config.js";
10
12
  * The e-mail is not a secret, but it is part of the authentication pair, and it
11
13
  * comes from the connect form through the operator-facing RPC. Keeping both
12
14
  * halves in one encrypted record means a token can never be paired with another
13
- * account's address, not even by a bug in the broker.
15
+ * account's address, not even by a bug in the broker. A Server / Data Center
16
+ * connection authenticates on the token alone and keeps the field empty: the
17
+ * instance's declared deployment type decides whether it is spent, which is why
18
+ * a credential is never paired with the other product's scheme.
14
19
  */
15
20
  export interface ConfluenceCredential {
16
21
  readonly instanceId: string;
@@ -24,15 +29,13 @@ export declare function credentialFromPlaintext(plaintext: string): ConfluenceCr
24
29
  * site, however permissive that one is.
25
30
  */
26
31
  export declare function credentialInstance(flags: ConfluenceFlags, credential: ConfluenceCredential): ConfluenceInstance;
27
- export interface ConfluenceQuery {
28
- readonly [key: string]: string | number | boolean | undefined;
29
- }
30
32
  /** What a listing answers about its own pagination, in provider terms. */
31
33
  export interface ConfluencePage {
32
34
  /**
33
- * Opaque token from the upstream `_links.next`, when the API is cursor-based.
34
- * It is never a URL: the whole point is that the next request is rebuilt from
35
- * our own path and parameters, so a caller cannot steer it.
35
+ * Opaque token from the upstream `_links.next`: a cursor on Cloud, the row
36
+ * offset of the next page on a Server / Data Center installation. It is never
37
+ * a URL: the whole point is that the next request is rebuilt from our own
38
+ * path and parameters, so a caller cannot steer it.
36
39
  */
37
40
  readonly nextCursor?: string | undefined;
38
41
  }
@@ -52,26 +55,12 @@ export declare class ConfluenceTransport {
52
55
  constructor(config: ResolvedQaIntegrationsConfig, flags: ConfluenceFlags, fetcher?: typeof fetch);
53
56
  getJson<T>(instance: ConfluenceInstance, credential: ConfluenceCredential, path: string, query?: ConfluenceQuery): Promise<ConfluenceJsonResponse<T>>;
54
57
  private url;
55
- /**
56
- * The one place the secret is spent. Basic authentication carries the account
57
- * e-mail and the API token; nothing else in the request names the user.
58
- */
59
- private authorization;
60
58
  private request;
61
- /** Atlassian asks for a pause through `retry-after`; honour it, but bounded. */
62
- private backoff;
63
- private retryDelay;
64
59
  /**
65
60
  * Confluence answers a page the account may not see with the same 404 as a
66
61
  * page that does not exist, and the provider keeps that ambiguity: the model
67
62
  * must not learn from an error whether someone else's page is there.
68
63
  */
69
64
  private failure;
70
- /**
71
- * Read a body without letting upstream decide how much memory the broker
72
- * spends. A body over the cap is reported as truncated instead of surfacing a
73
- * raw `content-length` nobody can verify.
74
- */
75
- private readText;
76
65
  }
77
66
  //# sourceMappingURL=transport.d.ts.map
@@ -1,5 +1,6 @@
1
+ import type { OperationSecurityMetadata } from "../../service-credentials/types.js";
1
2
  import type { IntegrationCapability, IntegrationCapabilityInfo } from "../../types.js";
2
- import type { JiraFlags } from "./config.js";
3
+ import type { JiraDeployment, JiraFlags } from "./config.js";
3
4
  /**
4
5
  * Capabilities this provider offers, one per kind of Jira data a user may hand
5
6
  * to the agent. They are narrower than what an Atlassian account can read on
@@ -30,6 +31,13 @@ export interface JiraOperationDefinition {
30
31
  * model can never pick an endpoint of its own.
31
32
  */
32
33
  readonly path: string;
34
+ /**
35
+ * The path of this operation on a Server / Data Center instance, when the
36
+ * product does not serve the Cloud one. Every other operation is the same
37
+ * path under the instance's own `/rest/api/2` root, which is what
38
+ * {@link jiraOperationPath} resolves.
39
+ */
40
+ readonly serverPath?: string;
33
41
  /**
34
42
  * Every operation of this catalog is a read. The field exists so the package
35
43
  * gate can assert that, instead of trusting the path names to look harmless:
@@ -38,7 +46,17 @@ export interface JiraOperationDefinition {
38
46
  readonly method: "GET";
39
47
  /** Set when the operation answers with one page of a collection. */
40
48
  readonly list?: boolean;
49
+ /** What this operation does, how sensitive it is, who may reach it. */
50
+ readonly security: OperationSecurityMetadata;
41
51
  }
52
+ /**
53
+ * The resource kind every project-scoped operation of this provider is bounded
54
+ * by. The entries of a `projects` boundary are Jira project keys — the form
55
+ * every operation addresses a project by (`projects.get` takes a key, an issue
56
+ * key embeds its project's key). A listed numeric project id is honoured where
57
+ * Jira reports one, in a filtered search; a key is what an operator lists.
58
+ */
59
+ export declare const JIRA_RESOURCE_KIND = "projects";
42
60
  /**
43
61
  * Every model-reachable operation. The provider refuses any operation that is
44
62
  * not listed here, so this table — together with `capability` — is the
@@ -49,7 +67,9 @@ export interface JiraOperationDefinition {
49
67
  *
50
68
  * `issues.search` reads the enhanced search endpoint Jira Cloud serves today;
51
69
  * the legacy `/search` was removed by Atlassian, so a catalog that still named
52
- * it would answer with an error page instead of issues.
70
+ * it would answer with an error page instead of issues. A Server / Data Center
71
+ * instance is the other way round: it serves exactly the legacy `/search`, and
72
+ * that is why the operation declares a `serverPath` of its own.
53
73
  */
54
74
  export declare const JIRA_OPERATIONS: Readonly<Record<string, JiraOperationDefinition>>;
55
75
  /**
@@ -65,10 +85,37 @@ export declare const JIRA_COMPANION_PATHS: readonly string[];
65
85
  * in the same change as the catalog entry that uses it.
66
86
  */
67
87
  export declare const JIRA_READ_PATHS: readonly string[];
88
+ /**
89
+ * The same allow-list for a Server / Data Center instance, which serves the
90
+ * whole read surface under `/rest/api/2`. It is written out instead of being
91
+ * derived, so that every endpoint this provider may ever call on either product
92
+ * is a line somebody added on purpose — and the package gate asserts the two
93
+ * lists stay in step, entry for entry, apart from the search endpoint that the
94
+ * two products genuinely do not share.
95
+ */
96
+ export declare const JIRA_SERVER_READ_PATHS: readonly string[];
97
+ /**
98
+ * The path of one catalog operation on the site's own product: the declared
99
+ * Cloud path, or its Server / Data Center counterpart — the operation's own
100
+ * when the product serves a different endpoint, and the same path under the
101
+ * instance's `/rest/api/2` root otherwise.
102
+ */
103
+ export declare function jiraOperationPath(operation: string, deployment: JiraDeployment): string | undefined;
104
+ /** `/rest/api/3/x` as a Data Center instance spells it. */
105
+ export declare function mirrorToServer(path: string): string;
106
+ /** The two reads this provider makes that are not operations of the catalog. */
107
+ export type JiraCompanionRead = "serverInfo" | "userSearch";
108
+ /**
109
+ * The path of one companion read on the site's product: the deployment probe a
110
+ * connect makes, and the directory lookup behind a person named by name.
111
+ */
112
+ export declare function jiraCompanionPath(read: JiraCompanionRead, deployment: JiraDeployment): string;
68
113
  /** Capabilities this deployment allows, in catalog order. */
69
114
  export declare function enabledCapabilities(flags: JiraFlags): readonly JiraCapability[];
70
115
  /** Label and hint per capability, for clients that render what we declare. */
71
116
  export declare const JIRA_CAPABILITY_INFO: Readonly<Record<JiraCapability, IntegrationCapabilityInfo>>;
72
117
  /** Capability an operation needs, or undefined when the catalog has none. */
73
118
  export declare function jiraOperationCapability(operation: string): IntegrationCapability | undefined;
119
+ /** Security classification of an operation, or undefined when it is unknown. */
120
+ export declare function jiraOperationMetadata(operation: string): OperationSecurityMetadata | undefined;
74
121
  //# sourceMappingURL=catalog.d.ts.map
@@ -1,9 +1,22 @@
1
1
  import z from "@deepseek-ai/schemastery";
2
2
  /**
3
- * One Jira Cloud site the operator allows. A user never types a host: the
4
- * connect form picks from this list, so the broker cannot be pointed at an
5
- * arbitrary origin (the specification's SSRF rule) and a credential minted for
6
- * a site cannot be spent against another one.
3
+ * Which Jira this site is: Atlassian Cloud, or a self-hosted Server / Data
4
+ * Center instance. The two are different products behind one name — different
5
+ * API roots (`/rest/api/3` against `/rest/api/2`), different authentication
6
+ * (an Atlassian API token over HTTP Basic against a personal access token over
7
+ * Bearer), and different answers for the same read — so the deployment type is
8
+ * a property of the site the operator declares, never a guess this provider
9
+ * makes at run time.
10
+ *
11
+ * Server and Data Center are one value on purpose: Data Center is Server with
12
+ * clustering, and the REST surface they answer is the same one.
13
+ */
14
+ export type JiraDeployment = "cloud" | "server";
15
+ /**
16
+ * One Jira site the operator allows. A user never types a host: the connect
17
+ * form picks from this list, so the broker cannot be pointed at an arbitrary
18
+ * origin (the specification's SSRF rule) and a credential minted for a site
19
+ * cannot be spent against another one.
7
20
  *
8
21
  * The Atlassian account behind a site is a tenant of this deployment, not a
9
22
  * global discriminator: the same person may reach several sites, and the
@@ -14,6 +27,8 @@ export interface JiraSite {
14
27
  readonly label: string;
15
28
  /** Canonical `<origin><path>`, without a trailing slash. */
16
29
  readonly baseUrl: string;
30
+ /** Which product answers at `baseUrl`; see {@link JiraDeployment}. */
31
+ readonly deploymentType: JiraDeployment;
17
32
  }
18
33
  /**
19
34
  * Deployment switches for the Jira provider. Every read capability is on by
@@ -54,6 +69,22 @@ export interface JiraFlags {
54
69
  }
55
70
  /** Jira Cloud caps one search page at 100 issues once fields are requested. */
56
71
  export declare const SEARCH_PAGE_CAP = 100;
72
+ /**
73
+ * One site as the operator writes it. `deploymentType` is spelled as a plain
74
+ * string here and resolved below, so that a config which predates the field
75
+ * keeps loading as the Cloud site it always was, and a typo is refused with the
76
+ * accepted values instead of silently becoming a default.
77
+ */
78
+ export interface JiraSiteInput {
79
+ readonly id: string;
80
+ readonly label?: string;
81
+ readonly baseUrl: string;
82
+ readonly deploymentType?: string;
83
+ }
84
+ /** Config slice as YAML writes it: every member is optional there. */
85
+ export interface JiraConfigInput extends Partial<Omit<JiraFlags, "sites">> {
86
+ readonly sites?: readonly JiraSiteInput[] | undefined;
87
+ }
57
88
  /**
58
89
  * The shape of a custom field id, as Jira spells it. The provider never carries
59
90
  * one itself: an id belongs to an instance, so it arrives either from the
@@ -66,8 +97,8 @@ export declare const JIRA_DEFAULTS: JiraFlags;
66
97
  * list is validated and canonicalized by `resolveJiraConfig`, which is where a
67
98
  * deployment typo fails loudly.
68
99
  */
69
- export declare const jiraConfigSchema: z<Partial<JiraFlags>>;
70
- export declare function resolveJiraConfig(input?: Partial<JiraFlags>): JiraFlags;
100
+ export declare const jiraConfigSchema: z<JiraConfigInput>;
101
+ export declare function resolveJiraConfig(input?: JiraConfigInput): JiraFlags;
71
102
  /** The configured site a stored credential names, or undefined. */
72
103
  export declare function jiraSite(flags: JiraFlags, siteId: string): JiraSite | undefined;
73
104
  //# sourceMappingURL=config.d.ts.map
@@ -1,8 +1,16 @@
1
1
  import type { CredentialHelp } from "@yadsh/dsh-plugin-kit";
2
2
  /**
3
- * Jira authenticates with an Atlassian API token next to the account e-mail.
4
- * Scoped tokens are the ones to recommend: an unscoped token is account-wide,
5
- * while a scoped one can be limited to the Jira scopes the agent actually uses.
3
+ * Jira authenticates in one of two ways, depending on where it runs. Atlassian
4
+ * Cloud takes an API token next to the account e-mail; a self-hosted Server /
5
+ * Data Center instance takes a personal access token and no account, because
6
+ * the token belongs to the account that minted it. Which one the connect form
7
+ * asks for follows the site the operator configured, and the instructions name
8
+ * both so the page is not wrong for either product.
9
+ *
10
+ * Scoped tokens are the ones to recommend on Cloud: an unscoped token is
11
+ * account-wide, while a scoped one can be limited to the Jira scopes the agent
12
+ * actually uses. A personal access token has no scopes of its own; the account's
13
+ * own Jira permissions are the whole boundary.
6
14
  */
7
15
  export declare const JIRA_CREDENTIAL_HELP: CredentialHelp;
8
16
  //# sourceMappingURL=credential-help.d.ts.map
@@ -0,0 +1,79 @@
1
+ import type { JiraDeployment, JiraSite } from "./config.js";
2
+ /**
3
+ * Everything that differs between Atlassian Cloud and a self-hosted Server /
4
+ * Data Center instance, in one place. The provider is one read-only product
5
+ * surface over two products: keeping the differences here means an operation
6
+ * asks the dialect where to read and how to authenticate, instead of every
7
+ * call site deciding for itself which Jira it is talking to.
8
+ *
9
+ * Nothing here is inferred at run time. The deployment type comes from the
10
+ * operator's site list, and a site that answers a different product than it
11
+ * declared is refused — the specification forbids treating Data Center as
12
+ * silently compatible with Cloud.
13
+ */
14
+ export interface JiraDialect {
15
+ readonly deployment: JiraDeployment;
16
+ /** Root every REST path of this product hangs under. */
17
+ readonly apiRoot: "/rest/api/3" | "/rest/api/2";
18
+ /** What the connect form calls the secret this product accepts. */
19
+ readonly credentialLabel: string;
20
+ /** Shape of one pasteable token, before anything is sent upstream. */
21
+ readonly tokenShape: RegExp;
22
+ /**
23
+ * Whether an e-mail must travel with the token. Cloud pairs an API token with
24
+ * the account it was minted for; a Server / Data Center personal access token
25
+ * authenticates on its own.
26
+ */
27
+ readonly requiresEmail: boolean;
28
+ /** The user directory parameter a free-text person is searched by. */
29
+ readonly userSearchParam: "query" | "username";
30
+ /** Fields a person is identified by in an answer, in order of preference. */
31
+ readonly identityFields: readonly string[];
32
+ /** `deploymentType` values `serverInfo` answers for this product. */
33
+ readonly deploymentTypes: readonly string[];
34
+ /** How the name of this product reads in a message. */
35
+ readonly productName: string;
36
+ }
37
+ export declare const JIRA_DIALECTS: Readonly<Record<JiraDeployment, JiraDialect>>;
38
+ /** The dialect of one configured site. */
39
+ export declare function dialectOf(site: JiraSite): JiraDialect;
40
+ /**
41
+ * The identifier of one person as an answer reports it. Cloud names an account
42
+ * id, a Server / Data Center instance the user name its JQL filters on; reading
43
+ * them in the dialect's own order is what keeps the identity of a connection
44
+ * the same value the model has to pass back in a filter.
45
+ */
46
+ export declare function identityOf(dialect: JiraDialect, person: Readonly<Record<string, unknown>>): string | undefined;
47
+ /**
48
+ * Jira Cloud authenticates an API token with HTTP Basic over `email:token`.
49
+ * The e-mail is not a secret, but it is what makes the token usable, so the two
50
+ * travel as one pair and never as two arguments.
51
+ */
52
+ export declare function basicAuthorization(credential: {
53
+ readonly email: string;
54
+ readonly token: string;
55
+ }): string;
56
+ /**
57
+ * The `Authorization` header of one stored credential. Cloud spends an
58
+ * Atlassian API token as HTTP Basic over `email:token`; a Server / Data Center
59
+ * personal access token is a bearer token, and the account it belongs to is the
60
+ * token's own — no e-mail travels with it.
61
+ *
62
+ * The credential carries what the operator's site declared, so a site whose
63
+ * deployment type no longer matches the credential is refused here, before the
64
+ * secret is spent: a token minted for one product must not be offered to the
65
+ * other.
66
+ */
67
+ export declare function authorizationFor(dialect: JiraDialect, credential: {
68
+ readonly email: string;
69
+ readonly token: string;
70
+ }): string;
71
+ /**
72
+ * Whether a `serverInfo` answer proves the site is the product it declared. An
73
+ * answer that names no type at all proves nothing either way and is left to the
74
+ * identity call that already succeeded; an answer that names the other product
75
+ * is a configuration mistake the operator has to fix, and the message says
76
+ * which one.
77
+ */
78
+ export declare function assertDeployment(dialect: JiraDialect, deploymentType: string | undefined): void;
79
+ //# sourceMappingURL=dialect.d.ts.map