From 46054cd3cf6014d953b94ecff17dd9da034ceb6e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 18 Feb 2023 00:06:22 +0000 Subject: [PATCH 1/2] chore(deps-dev): Bump jsii-docgen from 7.0.235 to 7.1.0 Bumps [jsii-docgen](https://github.com/cdklabs/jsii-docgen) from 7.0.235 to 7.1.0. - [Release notes](https://github.com/cdklabs/jsii-docgen/releases) - [Changelog](https://github.com/cdklabs/jsii-docgen/blob/main/CHANGELOG.md) - [Commits](https://github.com/cdklabs/jsii-docgen/compare/v7.0.235...v7.1.0) --- updated-dependencies: - dependency-name: jsii-docgen dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index 68dee0a5..0de56f34 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3965,9 +3965,9 @@ jsii-diff@^1.70.0: yargs "^16.2.0" jsii-docgen@^7.0.126: - version "7.0.235" - resolved "https://registry.yarnpkg.com/jsii-docgen/-/jsii-docgen-7.0.235.tgz#6de6a508f2cb62de5e859315d8baa99cfc4a66e0" - integrity sha512-esS/206w3+xhSpTPJaNWqIb2DIVCQiAoaSnbsKwhmrSE8Fll2mzIhHoipJTmfYzizhUk/ft6Y8/eC2NvDOhjwg== + version "7.1.0" + resolved "https://registry.yarnpkg.com/jsii-docgen/-/jsii-docgen-7.1.0.tgz#335c44f270dc0bfd7ea634ef30a7c06ba25e986e" + integrity sha512-7k90mHani3yNr2U/Gx2JBrgke3p2pp0qnNesb9gwoVj7mNgzUmWdssDy9dz+4GA+JqzAV0eI4mIJcEOvwzzN8w== dependencies: "@jsii/spec" "^1.75.0" case "^1.6.3" From 4614f7e778aa25e9f6dc9c162a2b007348733d46 Mon Sep 17 00:00:00 2001 From: github-actions Date: Sat, 18 Feb 2023 00:09:34 +0000 Subject: [PATCH 2/2] chore: self mutation Signed-off-by: github-actions --- API.md.md | 680 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 680 insertions(+) create mode 100644 API.md.md diff --git a/API.md.md b/API.md.md new file mode 100644 index 00000000..07a29624 --- /dev/null +++ b/API.md.md @@ -0,0 +1,680 @@ +# API Reference + +## Constructs + +### GithubCustomResource + +```typescript const auth = secrets_manager.Secret.fromSecretNameV2(scope, "Auth", "cdk-github/github-token"); + +new GithubCustomResource(scope, "GithubRepo", { + onCreate: { + // https://octokit.github.io/rest.js/v19/#repos-create-in-org + endpoint: "repos", + method: "createInOrg", + parameters: { + org: "pepperize", + name: "cdk-github", + }, + outputPaths: ["id", "full_name"], + physicalResourceId: custom_resources.PhysicalResourceId.fromResponse("full_name"), + ignoreErrorCodesMatching: "name already exists on this account", + }, + onUpdate: { + // https://octokit.github.io/rest.js/v19#repos-get + endpoint: "repos", + method: "get", + parameters: { + owner: "pepperize", + repo: "cdk-github", + }, + outputPaths: ["id", "full_name"], + physicalResourceId: custom_resources.PhysicalResourceId.fromResponse("full_name"), + }, + onDelete: { + // https://octokit.github.io/rest.js/v19#repos-delete + endpoint: "repos", + method: "delete", + parameters: { + owner: "pepperize", + repo: "cdk-github", + }, + outputPaths: [], + }, + authOptions: AuthOptions.appAuth(auth), +}); +``` + +#### Initializers + +```typescript +import { GithubCustomResource } from '@pepperize/cdk-github' + +new GithubCustomResource(scope: Construct, id: string, props: GithubCustomResourceProps) +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | GithubCustomResourceProps | *No description.* | + +--- + +##### `scope`Required + +- *Type:* constructs.Construct + +--- + +##### `id`Required + +- *Type:* string + +--- + +##### `props`Required + +- *Type:* GithubCustomResourceProps + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| getAtt | Returns the value of an attribute of the custom resource of an arbitrary type. | +| getAttString | Returns the value of an attribute of the custom resource of type string. | + +--- + +##### `toString` + +```typescript +public toString(): string +``` + +Returns a string representation of this construct. + +##### `getAtt` + +```typescript +public getAtt(attributeName: string): Reference +``` + +Returns the value of an attribute of the custom resource of an arbitrary type. + +Attributes are returned from the custom resource provider through the +`Data` map where the key is the attribute name. + +###### `attributeName`Required + +- *Type:* string + +the name of the attribute. + +--- + +##### `getAttString` + +```typescript +public getAttString(attributeName: string): string +``` + +Returns the value of an attribute of the custom resource of type string. + +Attributes are returned from the custom resource provider through the +`Data` map where the key is the attribute name. + +###### `attributeName`Required + +- *Type:* string + +the name of the attribute. + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Checks if `x` is a construct. | + +--- + +##### ~~`isConstruct`~~ + +```typescript +import { GithubCustomResource } from '@pepperize/cdk-github' + +GithubCustomResource.isConstruct(x: any) +``` + +Checks if `x` is a construct. + +###### `x`Required + +- *Type:* any + +Any object. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| ref | string | The physical name of this custom resource. | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `ref`Required + +```typescript +public readonly ref: string; +``` + +- *Type:* string + +The physical name of this custom resource. + +--- + + +### GithubCustomResourceBase + +#### Initializers + +```typescript +import { GithubCustomResourceBase } from '@pepperize/cdk-github' + +new GithubCustomResourceBase(scope: Construct, id: string) +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | The scope in which to define this construct. | +| id | string | The scoped construct ID. | + +--- + +##### `scope`Required + +- *Type:* constructs.Construct + +The scope in which to define this construct. + +--- + +##### `id`Required + +- *Type:* string + +The scoped construct ID. + +Must be unique amongst siblings. If +the ID includes a path separator (`/`), then it will be replaced by double +dash `--`. + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| getAtt | Returns the value of an attribute of the custom resource of an arbitrary type. | +| getAttString | Returns the value of an attribute of the custom resource of type string. | + +--- + +##### `toString` + +```typescript +public toString(): string +``` + +Returns a string representation of this construct. + +##### `getAtt` + +```typescript +public getAtt(attributeName: string): Reference +``` + +Returns the value of an attribute of the custom resource of an arbitrary type. + +Attributes are returned from the custom resource provider through the +`Data` map where the key is the attribute name. + +###### `attributeName`Required + +- *Type:* string + +the name of the attribute. + +--- + +##### `getAttString` + +```typescript +public getAttString(attributeName: string): string +``` + +Returns the value of an attribute of the custom resource of type string. + +Attributes are returned from the custom resource provider through the +`Data` map where the key is the attribute name. + +###### `attributeName`Required + +- *Type:* string + +the name of the attribute. + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Checks if `x` is a construct. | + +--- + +##### ~~`isConstruct`~~ + +```typescript +import { GithubCustomResourceBase } from '@pepperize/cdk-github' + +GithubCustomResourceBase.isConstruct(x: any) +``` + +Checks if `x` is a construct. + +###### `x`Required + +- *Type:* any + +Any object. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| ref | string | The physical name of this custom resource. | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `ref`Required + +```typescript +public readonly ref: string; +``` + +- *Type:* string + +The physical name of this custom resource. + +--- + + +## Structs + +### GithubApiCall + +#### Initializer + +```typescript +import { GithubApiCall } from '@pepperize/cdk-github' + +const githubApiCall: GithubApiCall = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| endpoint | string | The endpoint to call. | +| method | string | The method to call. | +| ignoreErrorCodesMatching | string | The regex pattern to use to catch API errors. | +| outputPaths | string[] | Filter the data returned by the custom resource to specific paths in the API response. | +| parameters | any | The parameters for the service action. | +| physicalResourceId | aws-cdk-lib.custom_resources.PhysicalResourceId | The physical resource id of the custom resource for this call. | + +--- + +##### `endpoint`Required + +```typescript +public readonly endpoint: string; +``` + +- *Type:* string + +The endpoint to call. + +> [https://github.com/octokit/rest.js](https://github.com/octokit/rest.js) + +--- + +##### `method`Required + +```typescript +public readonly method: string; +``` + +- *Type:* string + +The method to call. + +> [https://github.com/octokit/rest.js](https://github.com/octokit/rest.js) + +--- + +##### `ignoreErrorCodesMatching`Optional + +```typescript +public readonly ignoreErrorCodesMatching: string; +``` + +- *Type:* string + +The regex pattern to use to catch API errors. + +The `message` property of the `RequestError` object will be tested against this pattern. If there is a match an error will not be thrown. + +--- + +##### `outputPaths`Optional + +```typescript +public readonly outputPaths: string[]; +``` + +- *Type:* string[] +- *Default:* undefined - it's recommended to define it + +Filter the data returned by the custom resource to specific paths in the API response. + +The total size of the response body can't exceed 4096 bytes. + +> [https://docs.github.com/en/rest + +Example for octokit.rest.repos.createInOrg: ['id', 'full_name', 'owner.id']](https://docs.github.com/en/rest + +Example for octokit.rest.repos.createInOrg: ['id', 'full_name', 'owner.id']) + +--- + +##### `parameters`Optional + +```typescript +public readonly parameters: any; +``` + +- *Type:* any + +The parameters for the service action. + +> [https://github.com/octokit/rest.js](https://github.com/octokit/rest.js) + +--- + +##### `physicalResourceId`Optional + +```typescript +public readonly physicalResourceId: PhysicalResourceId; +``` + +- *Type:* aws-cdk-lib.custom_resources.PhysicalResourceId +- *Default:* undefined - for "Create" requests, defaults to the event's RequestId, for "Update" and "Delete", defaults to the current `PhysicalResourceId`. + +The physical resource id of the custom resource for this call. + +> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html) + +--- + +### GithubCustomResourceOptions + +#### Initializer + +```typescript +import { GithubCustomResourceOptions } from '@pepperize/cdk-github' + +const githubCustomResourceOptions: GithubCustomResourceOptions = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| authOptions | IAuthOptions | Currently, supports only GitHub App. | + +--- + +##### `authOptions`Required + +```typescript +public readonly authOptions: IAuthOptions; +``` + +- *Type:* IAuthOptions + +Currently, supports only GitHub App. + +```typescript +const auth = { appId, privateKey }; +const installationAuth = { appId, privateKey, installationId }; +``` + +> [https://github.com/octokit/authentication-strategies.js/#github-app-or-installation-authentication](https://github.com/octokit/authentication-strategies.js/#github-app-or-installation-authentication) + +--- + +### GithubCustomResourceProps + +#### Initializer + +```typescript +import { GithubCustomResourceProps } from '@pepperize/cdk-github' + +const githubCustomResourceProps: GithubCustomResourceProps = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| authOptions | IAuthOptions | Currently, supports only GitHub App. | +| onCreate | GithubApiCall | The GitHub Api call to make when the resource is created. | +| onDelete | GithubApiCall | The GitHub Api call to make when the resource is deleted. | +| onUpdate | GithubApiCall | The GitHub Api call to make when the resource is updated. | +| resourceType | string | Cloudformation Resource type. | + +--- + +##### `authOptions`Required + +```typescript +public readonly authOptions: IAuthOptions; +``` + +- *Type:* IAuthOptions + +Currently, supports only GitHub App. + +```typescript +const auth = { appId, privateKey }; +const installationAuth = { appId, privateKey, installationId }; +``` + +> [https://github.com/octokit/authentication-strategies.js/#github-app-or-installation-authentication](https://github.com/octokit/authentication-strategies.js/#github-app-or-installation-authentication) + +--- + +##### `onCreate`Optional + +```typescript +public readonly onCreate: GithubApiCall; +``` + +- *Type:* GithubApiCall + +The GitHub Api call to make when the resource is created. + +--- + +##### `onDelete`Optional + +```typescript +public readonly onDelete: GithubApiCall; +``` + +- *Type:* GithubApiCall + +The GitHub Api call to make when the resource is deleted. + +--- + +##### `onUpdate`Optional + +```typescript +public readonly onUpdate: GithubApiCall; +``` + +- *Type:* GithubApiCall + +The GitHub Api call to make when the resource is updated. + +--- + +##### `resourceType`Optional + +```typescript +public readonly resourceType: string; +``` + +- *Type:* string + +Cloudformation Resource type. + +--- + +## Classes + +### AuthOptions + +- *Implements:* IAuthOptions + +#### Initializers + +```typescript +import { AuthOptions } from '@pepperize/cdk-github' + +new AuthOptions() +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | + +--- + + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| appAuth | GitHub App or installation authentication. | +| tokenAuth | Personal Access Token authentication. | +| unauthenticated | unauthenticated. | + +--- + +##### `appAuth` + +```typescript +import { AuthOptions } from '@pepperize/cdk-github' + +AuthOptions.appAuth(secret: ISecret) +``` + +GitHub App or installation authentication. + +> [https://github.com/octokit/auth-app.js/#readme](https://github.com/octokit/auth-app.js/#readme) + +###### `secret`Required + +- *Type:* aws-cdk-lib.aws_secretsmanager.ISecret + +--- + +##### `tokenAuth` + +```typescript +import { AuthOptions } from '@pepperize/cdk-github' + +AuthOptions.tokenAuth(parameter: IParameter) +``` + +Personal Access Token authentication. + +> [https://github.com/octokit/auth-token.js#readme](https://github.com/octokit/auth-token.js#readme) + +###### `parameter`Required + +- *Type:* aws-cdk-lib.aws_ssm.IParameter + +--- + +##### `unauthenticated` + +```typescript +import { AuthOptions } from '@pepperize/cdk-github' + +AuthOptions.unauthenticated() +``` + +unauthenticated. + +> [https://github.com/octokit/auth-unauthenticated.js#readme](https://github.com/octokit/auth-unauthenticated.js#readme) + + + +## Protocols + +### IAuthOptions + +- *Implemented By:* AuthOptions, IAuthOptions + + +