forges 0.0.0 → 0.1.0

package/dist/schema/Reaction.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "content": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ReactionContent"
+        },
+        {
+          "type": "string",
+          "const": "other"
+        }
+      ],
+      "description": "`'other'` where the forge's name has no entry in {@link ReactionContent}."
+    },
+    "contentRaw": {
+      "type": "string",
+      "description": "The forge's own name for the reaction, such as a GitLab award emoji or a Forgejo emoji."
+    },
+    "actor": {
+      "$ref": "#/definitions/Actor"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "raw": {}
+  },
+  "required": [
+    "content",
+    "contentRaw",
+    "actor",
+    "raw"
+  ],
+  "description": "One reaction left on a thread or a comment, as `threads.reactions()` lists them.",
+  "x-forges-type": "Reaction",
+  "definitions": {
+    "Actor": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "login": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "avatarUrl": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "typeRaw": {
+          "type": "string",
+          "description": "Forge-reported account type, retained verbatim for callers that classify further."
+        },
+        "isBotHint": {
+          "type": "boolean",
+          "description": "Hint derived from forge metadata that the actor is automation. Callers own the classification policy."
+        },
+        "app": {
+          "type": "object",
+          "properties": {
+            "slug": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "slug"
+          ],
+          "description": "The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users)."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "isBotHint",
+        "login"
+      ],
+      "description": "An account: a user, an organisation or a bot.",
+      "x-forges-type": "Actor"
+    },
+    "ForgeInstance": {
+      "type": "string",
+      "description": "Host of a single forge deployment, for example `github.com` or `codeberg.org`.",
+      "x-forges-type": "ForgeInstance"
+    },
+    "ForgeKind": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/KnownForgeKind"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Identifier of a forge implementation. Unknown forges are permitted so that third-party providers can be registered without a core release.",
+      "x-forges-type": "ForgeKind"
+    },
+    "KnownForgeKind": {
+      "type": "string",
+      "enum": [
+        "github",
+        "gitlab",
+        "bitbucket",
+        "forgejo",
+        "gitea",
+        "tangled",
+        "gitee",
+        "azure-devops",
+        "cursor-origin",
+        "pushin"
+      ],
+      "description": "The forges this package ships providers for.",
+      "x-forges-type": "KnownForgeKind"
+    },
+    "ReactionContent": {
+      "type": "string",
+      "enum": [
+        "+1",
+        "-1",
+        "laugh",
+        "confused",
+        "heart",
+        "hooray",
+        "rocket",
+        "eyes"
+      ],
+      "description": "The reactions every forge with reactions has in common, named as GitHub names them. A {@link Reaction} whose forge-native name has no entry here has `content: 'other'`, with the forge-native name in `contentRaw`.",
+      "x-forges-type": "ReactionContent"
+    }
+  }
+}

package/dist/schema/ReactionContent.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "enum": [
+    "+1",
+    "-1",
+    "laugh",
+    "confused",
+    "heart",
+    "hooray",
+    "rocket",
+    "eyes"
+  ],
+  "description": "The reactions every forge with reactions has in common, named as GitHub names them. A {@link Reaction} whose forge-native name has no entry here has `content: 'other'`, with the forge-native name in `contentRaw`.",
+  "x-forges-type": "ReactionContent",
+  "definitions": {}
+}

package/dist/schema/ReactionSummary.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "total": {
+      "type": "number",
+      "description": "The number of reactions of every kind."
+    },
+    "counts": {
+      "type": "object",
+      "properties": {
+        "+1": {
+          "type": "number"
+        },
+        "-1": {
+          "type": "number"
+        },
+        "laugh": {
+          "type": "number"
+        },
+        "confused": {
+          "type": "number"
+        },
+        "heart": {
+          "type": "number"
+        },
+        "hooray": {
+          "type": "number"
+        },
+        "rocket": {
+          "type": "number"
+        },
+        "eyes": {
+          "type": "number"
+        }
+      },
+      "description": "The number of reactions of each kind. A reaction with no {@link ReactionContent} entry has no key here."
+    },
+    "viewerReacted": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ReactionContent"
+      },
+      "description": "Reactions the authenticated account has left. Absent when the forge does not report them."
+    }
+  },
+  "required": [
+    "total",
+    "counts"
+  ],
+  "description": "The reactions on a thread or comment, counted.",
+  "x-forges-type": "ReactionSummary",
+  "definitions": {
+    "ReactionContent": {
+      "type": "string",
+      "enum": [
+        "+1",
+        "-1",
+        "laugh",
+        "confused",
+        "heart",
+        "hooray",
+        "rocket",
+        "eyes"
+      ],
+      "description": "The reactions every forge with reactions has in common, named as GitHub names them. A {@link Reaction} whose forge-native name has no entry here has `content: 'other'`, with the forge-native name in `contentRaw`.",
+      "x-forges-type": "ReactionContent"
+    }
+  }
+}

package/dist/schema/Release.json

@@ -0,0 +1,286 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/ReleaseRef"
+    },
+    "name": {
+      "type": "string"
+    },
+    "tag": {
+      "type": "string"
+    },
+    "body": {
+      "type": "string",
+      "description": "The release notes."
+    },
+    "isDraft": {
+      "type": "boolean"
+    },
+    "isPrerelease": {
+      "type": "boolean"
+    },
+    "immutable": {
+      "type": "boolean",
+      "description": "The release is immutable: its tag and assets are locked. `true` where the forge supports immutable releases and this one is published as immutable (GitHub). The name, notes, prerelease and latest flags stay editable."
+    },
+    "author": {
+      "$ref": "#/definitions/Actor"
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "url": {
+      "type": "string"
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ReleaseAsset"
+      }
+    },
+    "raw": {}
+  },
+  "required": [
+    "ref",
+    "tag",
+    "isDraft",
+    "isPrerelease",
+    "raw"
+  ],
+  "description": "A release of a repository.",
+  "x-forges-type": "Release",
+  "definitions": {
+    "Actor": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "login": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "avatarUrl": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "typeRaw": {
+          "type": "string",
+          "description": "Forge-reported account type, retained verbatim for callers that classify further."
+        },
+        "isBotHint": {
+          "type": "boolean",
+          "description": "Hint derived from forge metadata that the actor is automation. Callers own the classification policy."
+        },
+        "app": {
+          "type": "object",
+          "properties": {
+            "slug": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "slug"
+          ],
+          "description": "The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users)."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "isBotHint",
+        "login"
+      ],
+      "description": "An account: a user, an organisation or a bot.",
+      "x-forges-type": "Actor"
+    },
+    "ForgeInstance": {
+      "type": "string",
+      "description": "Host of a single forge deployment, for example `github.com` or `codeberg.org`.",
+      "x-forges-type": "ForgeInstance"
+    },
+    "ForgeKind": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/KnownForgeKind"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Identifier of a forge implementation. Unknown forges are permitted so that third-party providers can be registered without a core release.",
+      "x-forges-type": "ForgeKind"
+    },
+    "KnownForgeKind": {
+      "type": "string",
+      "enum": [
+        "github",
+        "gitlab",
+        "bitbucket",
+        "forgejo",
+        "gitea",
+        "tangled",
+        "gitee",
+        "azure-devops",
+        "cursor-origin",
+        "pushin"
+      ],
+      "description": "The forges this package ships providers for.",
+      "x-forges-type": "KnownForgeKind"
+    },
+    "ReleaseAsset": {
+      "type": "object",
+      "properties": {
+        "ref": {
+          "$ref": "#/definitions/ReleaseAssetRef",
+          "description": "Absent where the forge publishes a download URL but nothing to address the asset by."
+        },
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "size": {
+          "type": "number"
+        },
+        "downloadCount": {
+          "type": "number"
+        },
+        "contentType": {
+          "type": "string",
+          "description": "The media type."
+        }
+      },
+      "required": [
+        "name",
+        "url"
+      ],
+      "description": "A file attached to a release.",
+      "x-forges-type": "ReleaseAsset"
+    },
+    "ReleaseAssetRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "repo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "release": {
+          "$ref": "#/definitions/ReleaseRef"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native asset id; the asset name, or the link id, on forges that have no asset id."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "release",
+        "repo"
+      ],
+      "description": "A release asset, addressable for download with `releases.downloadAsset`.",
+      "x-forges-type": "ReleaseAssetRef"
+    },
+    "ReleaseRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "repo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native release id; the tag name on forges that key releases by tag."
+        },
+        "tag": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo"
+      ],
+      "description": "A release, as a notification subject or event target.",
+      "x-forges-type": "ReleaseRef"
+    },
+    "RepoRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "owner": {
+          "type": "string",
+          "description": "Full namespace path. On forges with nested groups (GitLab) this contains slashes, for example `acme/platform`; `name` never does."
+        },
+        "name": {
+          "type": "string",
+          "description": "Repository name. Empty for namespace-scoped refs."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "repo",
+            "namespace"
+          ],
+          "description": "`'namespace'` for subjects that belong to a group rather than a repository (GitLab epics). Absent means a repository."
+        },
+        "externalId": {
+          "type": "string",
+          "description": "Stable forge-native identifier that survives renames and transfers: a GitHub, Forgejo or Gitea numeric id, a GitLab project or group id, a Bitbucket UUID or a Tangled repo DID. {@link repoKey} prefers it over `owner` and `name`."
+        }
+      },
+      "required": [
+        "forge",
+        "instance",
+        "name",
+        "owner"
+      ],
+      "description": "Addresses a repository by its forge, instance, owner and name.",
+      "x-forges-type": "RepoRef"
+    }
+  }
+}

package/dist/schema/ReleaseAsset.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/ReleaseAssetRef",
+      "description": "Absent where the forge publishes a download URL but nothing to address the asset by."
+    },
+    "name": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "size": {
+      "type": "number"
+    },
+    "downloadCount": {
+      "type": "number"
+    },
+    "contentType": {
+      "type": "string",
+      "description": "The media type."
+    }
+  },
+  "required": [
+    "name",
+    "url"
+  ],
+  "description": "A file attached to a release.",
+  "x-forges-type": "ReleaseAsset",
+  "definitions": {
+    "ForgeInstance": {
+      "type": "string",
+      "description": "Host of a single forge deployment, for example `github.com` or `codeberg.org`.",
+      "x-forges-type": "ForgeInstance"
+    },
+    "ForgeKind": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/KnownForgeKind"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Identifier of a forge implementation. Unknown forges are permitted so that third-party providers can be registered without a core release.",
+      "x-forges-type": "ForgeKind"
+    },
+    "KnownForgeKind": {
+      "type": "string",
+      "enum": [
+        "github",
+        "gitlab",
+        "bitbucket",
+        "forgejo",
+        "gitea",
+        "tangled",
+        "gitee",
+        "azure-devops",
+        "cursor-origin",
+        "pushin"
+      ],
+      "description": "The forges this package ships providers for.",
+      "x-forges-type": "KnownForgeKind"
+    },
+    "ReleaseAssetRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "repo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "release": {
+          "$ref": "#/definitions/ReleaseRef"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native asset id; the asset name, or the link id, on forges that have no asset id."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "release",
+        "repo"
+      ],
+      "description": "A release asset, addressable for download with `releases.downloadAsset`.",
+      "x-forges-type": "ReleaseAssetRef"
+    },
+    "ReleaseRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "repo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native release id; the tag name on forges that key releases by tag."
+        },
+        "tag": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo"
+      ],
+      "description": "A release, as a notification subject or event target.",
+      "x-forges-type": "ReleaseRef"
+    },
+    "RepoRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "owner": {
+          "type": "string",
+          "description": "Full namespace path. On forges with nested groups (GitLab) this contains slashes, for example `acme/platform`; `name` never does."
+        },
+        "name": {
+          "type": "string",
+          "description": "Repository name. Empty for namespace-scoped refs."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "repo",
+            "namespace"
+          ],
+          "description": "`'namespace'` for subjects that belong to a group rather than a repository (GitLab epics). Absent means a repository."
+        },
+        "externalId": {
+          "type": "string",
+          "description": "Stable forge-native identifier that survives renames and transfers: a GitHub, Forgejo or Gitea numeric id, a GitLab project or group id, a Bitbucket UUID or a Tangled repo DID. {@link repoKey} prefers it over `owner` and `name`."
+        }
+      },
+      "required": [
+        "forge",
+        "instance",
+        "name",
+        "owner"
+      ],
+      "description": "Addresses a repository by its forge, instance, owner and name.",
+      "x-forges-type": "RepoRef"
+    }
+  }
+}