@yadsh/dsh-qa-integrations 0.7.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 (141) hide show
  1. package/README.md +33 -16
  2. package/lib/client/confluence.js +37 -16
  3. package/lib/client/confluence.js.map +1 -1
  4. package/lib/client/jira.js +32 -11
  5. package/lib/client/jira.js.map +1 -1
  6. package/lib/client.js +128 -73
  7. package/lib/client.js.map +1 -1
  8. package/lib/coerce.js +17 -1
  9. package/lib/coerce.js.map +1 -1
  10. package/lib/config.js.map +1 -1
  11. package/lib/errors.js +22 -0
  12. package/lib/errors.js.map +1 -1
  13. package/lib/index.js +20 -2
  14. package/lib/index.js.map +1 -1
  15. package/lib/providers/bitrix24/config.js +2 -3
  16. package/lib/providers/bitrix24/config.js.map +1 -1
  17. package/lib/providers/bitrix24/index.js +1 -14
  18. package/lib/providers/bitrix24/index.js.map +1 -1
  19. package/lib/providers/bitrix24/operations.js +5 -9
  20. package/lib/providers/bitrix24/operations.js.map +1 -1
  21. package/lib/providers/bitrix24/transport.js +11 -31
  22. package/lib/providers/bitrix24/transport.js.map +1 -1
  23. package/lib/providers/confluence/adf.js +28 -23
  24. package/lib/providers/confluence/adf.js.map +1 -1
  25. package/lib/providers/confluence/catalog.js +40 -4
  26. package/lib/providers/confluence/catalog.js.map +1 -1
  27. package/lib/providers/confluence/config.js +27 -2
  28. package/lib/providers/confluence/config.js.map +1 -1
  29. package/lib/providers/confluence/credential-help.js +14 -8
  30. package/lib/providers/confluence/credential-help.js.map +1 -1
  31. package/lib/providers/confluence/dialect.js +215 -0
  32. package/lib/providers/confluence/dialect.js.map +1 -0
  33. package/lib/providers/confluence/index.js +137 -81
  34. package/lib/providers/confluence/index.js.map +1 -1
  35. package/lib/providers/confluence/operations.js +207 -152
  36. package/lib/providers/confluence/operations.js.map +1 -1
  37. package/lib/providers/confluence/storage.js +690 -0
  38. package/lib/providers/confluence/storage.js.map +1 -0
  39. package/lib/providers/confluence/transport.js +26 -89
  40. package/lib/providers/confluence/transport.js.map +1 -1
  41. package/lib/providers/gitlab/config.js +2 -3
  42. package/lib/providers/gitlab/config.js.map +1 -1
  43. package/lib/providers/gitlab/index.js +2 -20
  44. package/lib/providers/gitlab/index.js.map +1 -1
  45. package/lib/providers/gitlab/operations.js +7 -45
  46. package/lib/providers/gitlab/operations.js.map +1 -1
  47. package/lib/providers/gitlab/transport.js +2 -18
  48. package/lib/providers/gitlab/transport.js.map +1 -1
  49. package/lib/providers/jira/adf.js +19 -14
  50. package/lib/providers/jira/adf.js.map +1 -1
  51. package/lib/providers/jira/catalog.js +52 -1
  52. package/lib/providers/jira/catalog.js.map +1 -1
  53. package/lib/providers/jira/config.js +27 -2
  54. package/lib/providers/jira/config.js.map +1 -1
  55. package/lib/providers/jira/credential-help.js +16 -7
  56. package/lib/providers/jira/credential-help.js.map +1 -1
  57. package/lib/providers/jira/dialect.js +94 -0
  58. package/lib/providers/jira/dialect.js.map +1 -0
  59. package/lib/providers/jira/index.js +101 -95
  60. package/lib/providers/jira/index.js.map +1 -1
  61. package/lib/providers/jira/jql.js +54 -21
  62. package/lib/providers/jira/jql.js.map +1 -1
  63. package/lib/providers/jira/operations.js +77 -55
  64. package/lib/providers/jira/operations.js.map +1 -1
  65. package/lib/providers/jira/tools.js +1 -1
  66. package/lib/providers/jira/tools.js.map +1 -1
  67. package/lib/providers/jira/transport.js +12 -83
  68. package/lib/providers/jira/transport.js.map +1 -1
  69. package/lib/providers/shared/health.js +31 -0
  70. package/lib/providers/shared/health.js.map +1 -0
  71. package/lib/providers/shared/http.js +20 -0
  72. package/lib/providers/shared/http.js.map +1 -1
  73. package/lib/providers/shared/paths.js +14 -0
  74. package/lib/providers/shared/paths.js.map +1 -0
  75. package/lib/providers/shared/payload.js +46 -0
  76. package/lib/providers/shared/payload.js.map +1 -0
  77. package/lib/providers/teamcity/artifacts.js +0 -8
  78. package/lib/providers/teamcity/artifacts.js.map +1 -1
  79. package/lib/providers/teamcity/config.js +2 -3
  80. package/lib/providers/teamcity/config.js.map +1 -1
  81. package/lib/providers/teamcity/index.js +2 -20
  82. package/lib/providers/teamcity/index.js.map +1 -1
  83. package/lib/providers/teamcity/operations.js +5 -39
  84. package/lib/providers/teamcity/operations.js.map +1 -1
  85. package/lib/providers/teamcity/transport.js +2 -11
  86. package/lib/providers/teamcity/transport.js.map +1 -1
  87. package/lib/providers/testit/config.js +2 -3
  88. package/lib/providers/testit/config.js.map +1 -1
  89. package/lib/providers/testit/index.js +2 -20
  90. package/lib/providers/testit/index.js.map +1 -1
  91. package/lib/providers/testit/operations.js +34 -63
  92. package/lib/providers/testit/operations.js.map +1 -1
  93. package/lib/providers/testit/transport.js +2 -18
  94. package/lib/providers/testit/transport.js.map +1 -1
  95. package/lib/providers/weblate/config.js +2 -3
  96. package/lib/providers/weblate/config.js.map +1 -1
  97. package/lib/providers/weblate/index.js +2 -19
  98. package/lib/providers/weblate/index.js.map +1 -1
  99. package/lib/providers/weblate/operations.js +3 -33
  100. package/lib/providers/weblate/operations.js.map +1 -1
  101. package/lib/providers/weblate/query.js +3 -6
  102. package/lib/providers/weblate/query.js.map +1 -1
  103. package/lib/providers/weblate/transport.js +2 -12
  104. package/lib/providers/weblate/transport.js.map +1 -1
  105. package/lib/service-credentials/config.js +2 -3
  106. package/lib/service-credentials/config.js.map +1 -1
  107. package/lib/typert.host.js +62 -55
  108. package/lib/typert.remote-client.d.ts +4 -4
  109. package/lib/typert.remote-client.js +58 -51
  110. package/lib/types/client/confluence.d.ts +5 -1
  111. package/lib/types/client/jira.d.ts +5 -1
  112. package/lib/types/coerce.d.ts +14 -0
  113. package/lib/types/config.d.ts +4 -4
  114. package/lib/types/errors.d.ts +16 -0
  115. package/lib/types/index.d.ts +10 -2
  116. package/lib/types/providers/bitrix24/index.d.ts +1 -0
  117. package/lib/types/providers/confluence/catalog.d.ts +33 -5
  118. package/lib/types/providers/confluence/config.d.ts +39 -7
  119. package/lib/types/providers/confluence/credential-help.d.ts +9 -4
  120. package/lib/types/providers/confluence/dialect.d.ts +113 -0
  121. package/lib/types/providers/confluence/index.d.ts +24 -4
  122. package/lib/types/providers/confluence/operations.d.ts +12 -4
  123. package/lib/types/providers/confluence/storage.d.ts +28 -0
  124. package/lib/types/providers/confluence/transport.d.ts +10 -21
  125. package/lib/types/providers/jira/catalog.d.ts +36 -2
  126. package/lib/types/providers/jira/config.d.ts +37 -6
  127. package/lib/types/providers/jira/credential-help.d.ts +11 -3
  128. package/lib/types/providers/jira/dialect.d.ts +79 -0
  129. package/lib/types/providers/jira/index.d.ts +32 -22
  130. package/lib/types/providers/jira/jql.d.ts +14 -4
  131. package/lib/types/providers/jira/operations.d.ts +3 -0
  132. package/lib/types/providers/jira/transport.d.ts +6 -13
  133. package/lib/types/providers/shared/health.d.ts +18 -0
  134. package/lib/types/providers/shared/http.d.ts +9 -0
  135. package/lib/types/providers/shared/paths.d.ts +10 -0
  136. package/lib/types/providers/shared/payload.d.ts +26 -0
  137. package/lib/types/providers/teamcity/artifacts.d.ts +0 -2
  138. package/lib/types/providers/teamcity/index.d.ts +2 -0
  139. package/lib/types/providers/testit/index.d.ts +2 -0
  140. package/lib/types/types.d.ts +8 -0
  141. package/package.json +5 -5
@@ -1,6 +1,6 @@
1
1
  import type { OperationSecurityMetadata } from "../../service-credentials/types.js";
2
2
  import type { IntegrationCapability, IntegrationCapabilityInfo } from "../../types.js";
3
- import type { ConfluenceFlags } from "./config.js";
3
+ import type { ConfluenceDeployment, ConfluenceFlags } from "./config.js";
4
4
  /**
5
5
  * Capabilities this provider offers. They are narrower than Confluence's own
6
6
  * scopes on purpose: one switch per kind of data, so the operator decides what
@@ -30,6 +30,14 @@ export interface ConfluenceOperationDefinition {
30
30
  * endpoint of its own.
31
31
  */
32
32
  readonly path: string;
33
+ /**
34
+ * The path of this operation on a Server / Data Center installation. The two
35
+ * products genuinely differ here — Cloud answers the v2 API under `/wiki`
36
+ * (`/wiki/api/v2/pages/:pageId`), a self-hosted installation its own v1 API
37
+ * (`/rest/api/content/:pageId`) — so nearly every read names both rather than
38
+ * deriving one from the other.
39
+ */
40
+ readonly serverPath: string;
33
41
  /** Set when the operation answers with one page of a collection. */
34
42
  readonly list?: boolean;
35
43
  /**
@@ -50,12 +58,32 @@ export declare const CONFLUENCE_RESOURCE_KIND = "spaces";
50
58
  * could change Confluence state, and the confirmation framework does not exist
51
59
  * yet.
52
60
  *
53
- * The mix of REST versions is deliberate. Confluence Cloud v2 covers pages,
54
- * comments, attachments, versions and spaces, and that is where the reads go;
55
- * the CQL search and the "who am I" call exist only in v1. Tools never see the
56
- * difference — an operation answers a normalized object either way.
61
+ * The mix of REST versions is deliberate. On Cloud the v2 API covers pages,
62
+ * comments, attachments, versions and spaces, and that is where those reads go,
63
+ * while the CQL search and the "who am I" call exist only in v1; on a Server /
64
+ * Data Center installation the whole surface is that v1 API. Each operation
65
+ * declares the endpoint of both products, and the dialect builds the request
66
+ * from the one the instance declared. Tools never see the difference — an
67
+ * operation answers a normalized object either way.
57
68
  */
58
69
  export declare const CONFLUENCE_OPERATIONS: Readonly<Record<string, ConfluenceOperationDefinition>>;
70
+ /**
71
+ * The inline comment collection of a Cloud page. The catalog declares the
72
+ * footer one as the operation's endpoint; the inline kind is the same collection
73
+ * under its own name, and it is declared here rather than derived, so both paths
74
+ * a request may reach are lines somebody added on purpose.
75
+ */
76
+ export declare const CONFLUENCE_INLINE_COMMENTS_PATH = "/wiki/api/v2/pages/:pageId/inline-comments";
77
+ /**
78
+ * The reads this provider performs that are not operations of the catalog: the
79
+ * replies of one comment, which Cloud keeps in a collection per comment kind
80
+ * and a Server / Data Center installation in the comment's own children.
81
+ */
82
+ export declare const CONFLUENCE_COMPANION_PATHS: readonly string[];
83
+ /** The same read on a Server / Data Center installation, which has one kind. */
84
+ export declare const CONFLUENCE_SERVER_COMPANION_PATHS: readonly string[];
85
+ /** The path of one operation on the instance's product. */
86
+ export declare function confluenceOperationPath(operation: string, deployment: ConfluenceDeployment): string | undefined;
59
87
  /** Capabilities this deployment allows, in catalog order. */
60
88
  export declare function enabledCapabilities(flags: ConfluenceFlags): readonly ConfluenceCapability[];
61
89
  /** Label and hint per capability, for clients that render what we declare. */
@@ -1,20 +1,52 @@
1
1
  import z from "@deepseek-ai/schemastery";
2
+ /**
3
+ * Which Confluence this instance is: Atlassian Cloud, or a self-hosted Server /
4
+ * Data Center installation. The two are different products behind one name —
5
+ * Cloud answers the v2 API under `/wiki` with page bodies as Atlassian Document
6
+ * Format, while a Server / Data Center installation answers its own v1 API
7
+ * under `/rest/api` with page bodies as storage format — so the deployment type
8
+ * is a property of the instance the operator declares, never a guess this
9
+ * provider 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 ConfluenceDeployment = "cloud" | "server";
2
15
  /**
3
16
  * One Confluence site the operator allows. A user never types a host: the
4
17
  * connect form only picks from this list, so the broker cannot be pointed at an
5
18
  * arbitrary origin.
6
19
  *
7
- * The address is the site origin a Confluence Cloud deployment answers on
8
- * (`https://company.atlassian.net`). Deployments that reach Confluence through
9
- * the Atlassian gateway for scoped API tokens configure that base instead
10
- * (`https://api.atlassian.com/ex/confluence/<cloudId>`); both spell the same
11
- * relative `/wiki/...` paths, so the provider needs no mode switch.
20
+ * The address is the base every relative path of the product hangs under. Cloud
21
+ * answers on the site origin (`https://company.atlassian.net`, with `/wiki` as
22
+ * part of the path) or, for scoped API tokens, on the gateway
23
+ * (`https://api.atlassian.com/ex/confluence/<cloudId>`). A Server / Data Center
24
+ * installation is named by its own address, and an installation behind a context
25
+ * path spells that path here (`https://wiki.example.corp/confluence`).
12
26
  */
13
27
  export interface ConfluenceInstance {
14
28
  readonly id: string;
15
29
  readonly label: string;
16
30
  /** Canonical `<origin><path>`, without a trailing slash. */
17
31
  readonly baseUrl: string;
32
+ /** Which product answers at `baseUrl`; see {@link ConfluenceDeployment}. */
33
+ readonly deploymentType: ConfluenceDeployment;
34
+ }
35
+ /**
36
+ * One instance as the operator writes it. `deploymentType` is spelled as a
37
+ * plain string here and resolved below, so a config written before the field
38
+ * existed keeps loading as the Cloud site it always was, and a typo is refused
39
+ * with the accepted values instead of quietly becoming a default.
40
+ */
41
+ export interface ConfluenceInstanceInput {
42
+ readonly id: string;
43
+ readonly label?: string;
44
+ readonly baseUrl: string;
45
+ readonly deploymentType?: string;
46
+ }
47
+ /** Config slice as YAML writes it: every member is optional there. */
48
+ export interface ConfluenceConfigInput extends Partial<Omit<ConfluenceFlags, "instances">> {
49
+ readonly instances?: readonly ConfluenceInstanceInput[] | undefined;
18
50
  }
19
51
  /**
20
52
  * Deployment switches for the Confluence provider. Read capabilities are on by
@@ -59,8 +91,8 @@ export declare const CONFLUENCE_DEFAULTS: ConfluenceFlags;
59
91
  * instance list is validated and canonicalized by `resolveConfluenceConfig`,
60
92
  * which is where a deployment typo fails loudly.
61
93
  */
62
- export declare const confluenceConfigSchema: z<Partial<ConfluenceFlags>>;
63
- export declare function resolveConfluenceConfig(input?: Partial<ConfluenceFlags>): ConfluenceFlags;
94
+ export declare const confluenceConfigSchema: z<ConfluenceConfigInput>;
95
+ export declare function resolveConfluenceConfig(input?: ConfluenceConfigInput): ConfluenceFlags;
64
96
  /** The configured site a stored credential names, or a fail-closed error. */
65
97
  export declare function confluenceInstance(flags: ConfluenceFlags, instanceId: string): ConfluenceInstance | undefined;
66
98
  /** Whether a space key passes the operator allowlist; an empty list allows all. */
@@ -1,9 +1,14 @@
1
1
  import type { CredentialHelp } from "@yadsh/dsh-plugin-kit";
2
2
  /**
3
- * Confluence authenticates with an Atlassian API token next to the account
4
- * e-mail, and the token is account-wide: the same one opens Jira and the other
5
- * Atlassian Cloud products, so the scopes are about the account rather than
6
- * about Confluence alone.
3
+ * Confluence authenticates in one of two ways, depending on where it runs.
4
+ * Atlassian Cloud takes an API token next to the account e-mail, and that token
5
+ * is account-wide: the same one opens Jira and the other Atlassian Cloud
6
+ * products, so the scopes are about the account rather than about Confluence
7
+ * alone. A self-hosted Server / Data Center instance takes a personal access
8
+ * token and no account, because the token belongs to the account that minted
9
+ * it. Which one the connect form asks for follows the instance the operator
10
+ * configured, and the instructions name both so the page is not wrong for
11
+ * either product.
7
12
  */
8
13
  export declare const CONFLUENCE_CREDENTIAL_HELP: CredentialHelp;
9
14
  //# sourceMappingURL=credential-help.d.ts.map
@@ -0,0 +1,113 @@
1
+ import type { ConfluenceDeployment, ConfluenceInstance } from "./config.js";
2
+ /**
3
+ * Where one Confluence read lives, and how it pages. Cloud and Server / Data
4
+ * Center are two products behind one name: Cloud answers the v2 API relative to
5
+ * `/wiki` and pages its listings with an opaque cursor, while a self-hosted
6
+ * installation answers its own v1 API relative to `/rest/api` and pages by row
7
+ * offset. Everything that differs is a member of this interface, so an
8
+ * operation asks the dialect where to read instead of deciding for itself which
9
+ * Confluence it is talking to.
10
+ *
11
+ * Nothing here is inferred at run time: the deployment type comes from the
12
+ * operator's instance list, and a connection whose stored credential does not
13
+ * match it is refused.
14
+ */
15
+ export interface ConfluenceDialect {
16
+ readonly deployment: ConfluenceDeployment;
17
+ /** What the connect form calls the secret this product accepts. */
18
+ readonly credentialLabel: string;
19
+ /** Shape of one pasteable token, before anything is sent upstream. */
20
+ readonly tokenShape: RegExp;
21
+ /**
22
+ * Whether an account e-mail must travel with the token. Cloud spends an
23
+ * Atlassian API token as HTTP Basic over `email:token`; a Server / Data
24
+ * Center personal access token is a bearer token and needs no account.
25
+ */
26
+ readonly requiresEmail: boolean;
27
+ /** How the name of this product reads in a message. */
28
+ readonly productName: string;
29
+ /**
30
+ * Which page-addressed collection path one comment kind has, or none when the
31
+ * product keeps both kinds in one collection and marks them per comment.
32
+ */
33
+ readonly commentKinds: "path" | "marker";
34
+ /** The identity read a connect proves itself with. */
35
+ readonly currentUserPath: string;
36
+ /** The CQL search. */
37
+ searchPath(input: SearchInput): ConfluenceRead;
38
+ /** One space, by the key or id the model named. */
39
+ spacePath(ref: string): ConfluenceRead;
40
+ /** The space listing, filtered by keys when the caller named any. */
41
+ spaceList(input: SpaceListInput): ConfluenceRead;
42
+ /** The space a page belongs to, for the deployment's own space policy. */
43
+ pageSpacePath(pageId: string): ConfluenceRead;
44
+ /** One page with the body and metadata an answer carries. */
45
+ pagePath(pageId: string): ConfluenceRead;
46
+ /** The comments of one page; `kind` selects the collection where it can. */
47
+ commentPath(input: CommentInput): ConfluenceRead;
48
+ /** The replies of one comment. */
49
+ commentChildrenPath(input: CommentChildrenInput): ConfluenceRead;
50
+ /** The attachments of one page, metadata only. */
51
+ attachmentPath(input: PageInput): ConfluenceRead;
52
+ /** The versions of one page. */
53
+ versionPath(input: PageInput): ConfluenceRead;
54
+ }
55
+ /** One read: a path relative to the instance base, with its own parameters. */
56
+ export interface ConfluenceRead {
57
+ readonly path: string;
58
+ readonly query: ConfluenceQuery;
59
+ }
60
+ export interface PagedInput {
61
+ /** A continuation token this provider already shape-checked. */
62
+ readonly cursor: string | undefined;
63
+ readonly limit: number;
64
+ }
65
+ export interface SearchInput {
66
+ readonly cql: string;
67
+ /** Rows before this page; both products page a CQL search by offset. */
68
+ readonly start: number;
69
+ readonly limit: number;
70
+ /** Archived spaces are a Cloud concept; the field is ignored elsewhere. */
71
+ readonly includeArchived: boolean | undefined;
72
+ }
73
+ export interface SpaceListInput extends PagedInput {
74
+ readonly keys: readonly string[];
75
+ readonly type: string | undefined;
76
+ }
77
+ export interface CommentInput extends PagedInput {
78
+ readonly pageId: string;
79
+ readonly kind: "footer" | "inline";
80
+ }
81
+ export interface PageInput extends PagedInput {
82
+ readonly pageId: string;
83
+ }
84
+ export interface CommentChildrenInput extends PagedInput {
85
+ readonly commentId: string;
86
+ readonly kind: "footer" | "inline";
87
+ }
88
+ /**
89
+ * Query parameters of one read. Every value is a constant, a number, or a
90
+ * string this provider validated first — never caller input as-is.
91
+ */
92
+ export interface ConfluenceQuery {
93
+ readonly [key: string]: string | number | boolean | undefined;
94
+ }
95
+ export declare const CONFLUENCE_DIALECTS: Readonly<Record<ConfluenceDeployment, ConfluenceDialect>>;
96
+ /** The dialect of one configured instance. */
97
+ export declare function dialectOf(instance: ConfluenceInstance): ConfluenceDialect;
98
+ /**
99
+ * The `Authorization` header of one stored credential. Cloud spends an
100
+ * Atlassian API token as HTTP Basic over `email:token`; a Server / Data Center
101
+ * personal access token is a bearer token whose account is the token's own, so
102
+ * no e-mail travels with it.
103
+ *
104
+ * The credential carries what the operator's instance declared, so an instance
105
+ * whose deployment type no longer matches the stored credential is refused
106
+ * here, before the secret is spent: a token minted for one product must not be
107
+ * offered to the other.
108
+ */
109
+ export declare function authorizationFor(dialect: ConfluenceDialect, credential: {
110
+ readonly email: string;
111
+ readonly token: string;
112
+ }): string;
113
+ //# sourceMappingURL=dialect.d.ts.map
@@ -12,7 +12,15 @@ export { credentialFromPlaintext, credentialInstance, type ConfluenceCredential,
12
12
  * cases.
13
13
  */
14
14
  export declare function spaceInBoundary(boundary: ServiceResourceBoundary, key: string | undefined): boolean;
15
- /** Confluence provider: operator-configured sites over an Atlassian API token. */
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
+ */
16
24
  export declare class ConfluenceProvider implements IntegrationProvider {
17
25
  private readonly config;
18
26
  readonly id = "confluence";
@@ -38,9 +46,12 @@ export declare class ConfluenceProvider implements IntegrationProvider {
38
46
  * broker from dialling any host the caller names or authenticating as any
39
47
  * account the caller names.
40
48
  *
41
- * A deployment-managed secret cannot travel with a connect form, so it
42
- * arrives as the Basic pair Atlassian documents (`email:token`). The two
43
- * forms can never be confused: an API token contains neither `@` nor `:`.
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.
44
55
  */
45
56
  parseCredential(raw: string, options?: Readonly<Record<string, string>>): {
46
57
  readonly credential: string;
@@ -104,6 +115,13 @@ export declare class ConfluenceProvider implements IntegrationProvider {
104
115
  private listBoundedSpaces;
105
116
  /** The fields a space contributes to a page answer, plus its policy key. */
106
117
  private readSpaceFields;
118
+ /**
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;
107
125
  /**
108
126
  * The space of a page the call is about. Asked for whenever a policy needs
109
127
  * it: the deployment allowlist, or — in service mode — the boundary, which is
@@ -128,5 +146,7 @@ export declare class ConfluenceProvider implements IntegrationProvider {
128
146
  private projectionContext;
129
147
  private resolveInstance;
130
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. */
131
151
  export default ConfluenceProvider;
132
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. */
@@ -25,6 +25,12 @@ export declare function bodyLimit(value: unknown, flags: ConfluenceFlags): numbe
25
25
  * another user's data.
26
26
  */
27
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;
28
34
  /** v2 pagination is cursor-based; the token is shape-checked before it is spent. */
29
35
  export declare function upstreamCursor(value: unknown): string | undefined;
30
36
  /**
@@ -39,10 +45,10 @@ export type ConfluenceCommentKind = (typeof COMMENT_KINDS)[number];
39
45
  export declare function commentKind(value: unknown): ConfluenceCommentKind;
40
46
  /** Collections a kind reads; `all` is the two of them, in this order. */
41
47
  export declare function commentCollections(kind: ConfluenceCommentKind): readonly ("footer" | "inline")[];
42
- /** The page-relative collection path of one comment kind. */
43
- 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;
44
50
  /** The replies of one comment; the collection decides which endpoint owns them. */
45
- 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;
46
52
  export declare const SPACE_TYPES: readonly string[];
47
53
  export interface OperationContext {
48
54
  /**
@@ -53,6 +59,8 @@ export interface OperationContext {
53
59
  */
54
60
  readonly externalUserId?: string | undefined;
55
61
  readonly flags: ConfluenceFlags;
62
+ /** The product this instance is, which decides endpoints and paging. */
63
+ readonly dialect: ConfluenceDialect;
56
64
  }
57
65
  export interface ConfluenceRequest {
58
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,6 +1,6 @@
1
1
  import type { OperationSecurityMetadata } from "../../service-credentials/types.js";
2
2
  import type { IntegrationCapability, IntegrationCapabilityInfo } from "../../types.js";
3
- import type { JiraFlags } from "./config.js";
3
+ import type { JiraDeployment, JiraFlags } from "./config.js";
4
4
  /**
5
5
  * Capabilities this provider offers, one per kind of Jira data a user may hand
6
6
  * to the agent. They are narrower than what an Atlassian account can read on
@@ -31,6 +31,13 @@ export interface JiraOperationDefinition {
31
31
  * model can never pick an endpoint of its own.
32
32
  */
33
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;
34
41
  /**
35
42
  * Every operation of this catalog is a read. The field exists so the package
36
43
  * gate can assert that, instead of trusting the path names to look harmless:
@@ -60,7 +67,9 @@ export declare const JIRA_RESOURCE_KIND = "projects";
60
67
  *
61
68
  * `issues.search` reads the enhanced search endpoint Jira Cloud serves today;
62
69
  * the legacy `/search` was removed by Atlassian, so a catalog that still named
63
- * 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.
64
73
  */
65
74
  export declare const JIRA_OPERATIONS: Readonly<Record<string, JiraOperationDefinition>>;
66
75
  /**
@@ -76,6 +85,31 @@ export declare const JIRA_COMPANION_PATHS: readonly string[];
76
85
  * in the same change as the catalog entry that uses it.
77
86
  */
78
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;
79
113
  /** Capabilities this deployment allows, in catalog order. */
80
114
  export declare function enabledCapabilities(flags: JiraFlags): readonly JiraCapability[];
81
115
  /** Label and hint per capability, for clients that render what we declare. */
@@ -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