@foss.global/interfaces 0.7.0 → 0.9.0

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-07-21 - 0.9.0
+
+### Features
+
+- add native pull request contracts (pull-requests)
+  - Add public pull request, discussion, review, inline review comment, and merge state shapes.
+  - Add typed mutation contracts for pull request creation, state changes, review submission and dismissal, and generation-fenced merge queue operations.
+  - Extend repository public reads with pull request details and conversation data.
+
+## 2026-07-21 - 0.8.0
+
+### Features
+
+- add repository-scoped CI cache protocol contracts (ci-caches)
+  - Add exact cache key, declared restore path, save policy, and retention job specifications.
+  - Allow runners to advertise cache capability and return generation-fenced save metadata.
+  - Add export coverage for the new cache contract shapes.
+
 ## 2026-07-21 - 0.7.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/interfaces',
-    version: '0.7.0',
+    version: '0.9.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHFHQUFxRztDQUNuSCxDQUFBIn0=

package/dist_ts/data/public.d.ts

@@ -111,6 +111,72 @@ export interface IPublicIssueComment {
     updatedAt: string;
     user: IPublicUser;
 }
+export type TRepositoryPullRequestState = 'open' | 'closed' | 'merged';
+export type TRepositoryPullRequestMergeMethod = 'merge' | 'squash' | 'rebase';
+export type TRepositoryPullRequestMergeState = 'checking' | 'clean' | 'conflicting' | 'blocked' | 'queued' | 'merging' | 'merged' | 'failed';
+export type TRepositoryPullRequestReviewState = 'commented' | 'approved' | 'changes_requested' | 'dismissed';
+export type TRepositoryPullRequestReviewSide = 'base' | 'head';
+export interface IPublicPullRequest {
+    number: number;
+    title: string;
+    body: string;
+    htmlUrl: string;
+    state: TRepositoryPullRequestState;
+    draft: boolean;
+    sourceOrg: string;
+    sourceRepo: string;
+    sourceRef: string;
+    targetRef: string;
+    sourceObjectId: string;
+    targetObjectId: string;
+    mergeState: TRepositoryPullRequestMergeState;
+    mergeable: boolean | null;
+    mergeMethod: TRepositoryPullRequestMergeMethod | null;
+    mergeCommitId: string | null;
+    queuePosition: number | null;
+    comments: number;
+    reviews: number;
+    approvals: number;
+    changesRequested: number;
+    createdAt: string;
+    updatedAt: string;
+    closedAt: string | null;
+    mergedAt: string | null;
+    user: IPublicUser;
+    mergedBy: IPublicUser | null;
+}
+export interface IPublicPullRequestComment {
+    id: number;
+    body: string;
+    htmlUrl: string;
+    createdAt: string;
+    updatedAt: string;
+    user: IPublicUser;
+}
+export interface IPublicPullRequestReview {
+    id: number;
+    body: string;
+    htmlUrl: string;
+    state: TRepositoryPullRequestReviewState;
+    commitId: string;
+    submittedAt: string;
+    dismissedAt: string | null;
+    user: IPublicUser;
+}
+export interface IPublicPullRequestReviewComment {
+    id: number;
+    reviewId: number;
+    body: string;
+    path: string;
+    side: TRepositoryPullRequestReviewSide;
+    line: number;
+    commitId: string;
+    stale: boolean;
+    htmlUrl: string;
+    createdAt: string;
+    updatedAt: string;
+    user: IPublicUser;
+}
 export interface IPublicCommit {
     sha: string;
     shortSha: string;

package/dist_ts/data/runner.d.ts

@@ -4,6 +4,7 @@ export type TOciRuntime = 'docker' | 'podman';
 export type TJobNetwork = 'none' | 'bridge';
 export type TLogStream = 'stdout' | 'stderr' | 'runner';
 export type TJobArtifactWhen = 'always' | 'success' | 'failure';
+export type TJobCacheSaveWhen = 'always' | 'success';
 export type TJobCompletionStatus = 'succeeded' | 'failed' | 'canceled' | 'timed_out' | 'system_error';
 export type TCiJobState = 'queued' | 'running' | TJobCompletionStatus;
 export interface IRunnerCredential {
@@ -17,7 +18,7 @@ export interface IRunnerCapabilities {
     networks: TJobNetwork[];
     sourceArchives: ['tar.gz'];
     artifacts: boolean;
-    caches: false;
+    caches: boolean;
     serviceContainers: false;
 }
 export interface IRegisterRunnerRequest {
@@ -71,6 +72,13 @@ export interface IJobArtifactSpec {
     required?: boolean;
     retentionDays?: number;
 }
+export interface IJobCacheSpec {
+    name: string;
+    key: string;
+    paths: string[];
+    saveWhen?: TJobCacheSaveWhen;
+    retentionDays?: number;
+}
 export interface IJobSpec {
     image: string;
     command: string[];
@@ -81,6 +89,7 @@ export interface IJobSpec {
     resources?: IJobResources;
     source?: IJobSourceArchive;
     artifacts?: IJobArtifactSpec[];
+    caches?: IJobCacheSpec[];
 }
 export interface IJobLease {
     jobId: string;
@@ -135,6 +144,16 @@ export interface ICiArtifactUploadResponse {
     createdAt: string;
     expiresAt: string;
 }
+export interface ICiCacheSaveResponse {
+    name: string;
+    key: string;
+    generation: number;
+    sha256: string;
+    sizeBytes: number;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+}
 export interface ICompleteJobRequest extends IJobMutationIdentity {
     status: TJobCompletionStatus;
     exitCode: number | null;

package/dist_ts/requests/public.d.ts

@@ -42,6 +42,7 @@ export interface IReq_PublicRepo extends plugins.typedrequestInterfaces.implemen
         repo: string;
         path?: string;
         issueNumber?: number;
+        pullRequestNumber?: number;
     };
     response: {
         repo: data.IPublicRepo | null;
@@ -52,6 +53,11 @@ export interface IReq_PublicRepo extends plugins.typedrequestInterfaces.implemen
         issues: data.IPublicIssue[];
         selectedIssue: data.IPublicIssue | null;
         selectedIssueComments: data.IPublicIssueComment[];
+        pullRequests: data.IPublicPullRequest[];
+        selectedPullRequest: data.IPublicPullRequest | null;
+        selectedPullRequestComments: data.IPublicPullRequestComment[];
+        selectedPullRequestReviews: data.IPublicPullRequestReview[];
+        selectedPullRequestReviewComments: data.IPublicPullRequestReviewComment[];
         commits: data.IPublicCommit[];
         languages: Record<string, number>;
     };
@@ -170,3 +176,114 @@ export interface IReq_RepositoryIssueStateUpdate extends plugins.typedrequestInt
         issue: data.IPublicIssue;
     };
 }
+export interface IReq_RepositoryPullRequestCreate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestCreate> {
+    method: 'repositoryPullRequestCreate';
+    request: {
+        org: string;
+        repo: string;
+        title: string;
+        body: string;
+        sourceOrg: string;
+        sourceRepo: string;
+        sourceRef: string;
+        targetRef: string;
+        draft: boolean;
+        accessToken: string;
+    };
+    response: {
+        pullRequest: data.IPublicPullRequest;
+    };
+}
+export interface IReq_RepositoryPullRequestCommentCreate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestCommentCreate> {
+    method: 'repositoryPullRequestCommentCreate';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        body: string;
+        accessToken: string;
+    };
+    response: {
+        comment: data.IPublicPullRequestComment;
+    };
+}
+export interface IReq_RepositoryPullRequestStateUpdate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestStateUpdate> {
+    method: 'repositoryPullRequestStateUpdate';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        state: 'open' | 'closed';
+        draft?: boolean;
+        accessToken: string;
+    };
+    response: {
+        pullRequest: data.IPublicPullRequest;
+    };
+}
+export interface IRepositoryPullRequestReviewCommentInput {
+    body: string;
+    path: string;
+    side: data.TRepositoryPullRequestReviewSide;
+    line: number;
+}
+export interface IReq_RepositoryPullRequestReviewSubmit extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestReviewSubmit> {
+    method: 'repositoryPullRequestReviewSubmit';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        state: Exclude<data.TRepositoryPullRequestReviewState, 'dismissed'>;
+        body: string;
+        commitId: string;
+        comments: IRepositoryPullRequestReviewCommentInput[];
+        accessToken: string;
+    };
+    response: {
+        review: data.IPublicPullRequestReview;
+        comments: data.IPublicPullRequestReviewComment[];
+        pullRequest: data.IPublicPullRequest;
+    };
+}
+export interface IReq_RepositoryPullRequestReviewDismiss extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestReviewDismiss> {
+    method: 'repositoryPullRequestReviewDismiss';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        reviewId: number;
+        message: string;
+        accessToken: string;
+    };
+    response: {
+        review: data.IPublicPullRequestReview;
+        pullRequest: data.IPublicPullRequest;
+    };
+}
+export interface IReq_RepositoryPullRequestMergeEnqueue extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestMergeEnqueue> {
+    method: 'repositoryPullRequestMergeEnqueue';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        method: data.TRepositoryPullRequestMergeMethod;
+        expectedSourceObjectId: string;
+        expectedTargetObjectId: string;
+        accessToken: string;
+    };
+    response: {
+        pullRequest: data.IPublicPullRequest;
+    };
+}
+export interface IReq_RepositoryPullRequestMergeCancel extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RepositoryPullRequestMergeCancel> {
+    method: 'repositoryPullRequestMergeCancel';
+    request: {
+        org: string;
+        repo: string;
+        pullRequestNumber: number;
+        accessToken: string;
+    };
+    response: {
+        pullRequest: data.IPublicPullRequest;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/interfaces',
-  version: '0.7.0',
+  version: '0.9.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/public.ts

@@ -135,6 +135,93 @@ export interface IPublicIssueComment {
   user: IPublicUser;
 }
 
+export type TRepositoryPullRequestState = 'open' | 'closed' | 'merged';
+
+export type TRepositoryPullRequestMergeMethod = 'merge' | 'squash' | 'rebase';
+
+export type TRepositoryPullRequestMergeState =
+  | 'checking'
+  | 'clean'
+  | 'conflicting'
+  | 'blocked'
+  | 'queued'
+  | 'merging'
+  | 'merged'
+  | 'failed';
+
+export type TRepositoryPullRequestReviewState =
+  | 'commented'
+  | 'approved'
+  | 'changes_requested'
+  | 'dismissed';
+
+export type TRepositoryPullRequestReviewSide = 'base' | 'head';
+
+export interface IPublicPullRequest {
+  number: number;
+  title: string;
+  body: string;
+  htmlUrl: string;
+  state: TRepositoryPullRequestState;
+  draft: boolean;
+  sourceOrg: string;
+  sourceRepo: string;
+  sourceRef: string;
+  targetRef: string;
+  sourceObjectId: string;
+  targetObjectId: string;
+  mergeState: TRepositoryPullRequestMergeState;
+  mergeable: boolean | null;
+  mergeMethod: TRepositoryPullRequestMergeMethod | null;
+  mergeCommitId: string | null;
+  queuePosition: number | null;
+  comments: number;
+  reviews: number;
+  approvals: number;
+  changesRequested: number;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string | null;
+  mergedAt: string | null;
+  user: IPublicUser;
+  mergedBy: IPublicUser | null;
+}
+
+export interface IPublicPullRequestComment {
+  id: number;
+  body: string;
+  htmlUrl: string;
+  createdAt: string;
+  updatedAt: string;
+  user: IPublicUser;
+}
+
+export interface IPublicPullRequestReview {
+  id: number;
+  body: string;
+  htmlUrl: string;
+  state: TRepositoryPullRequestReviewState;
+  commitId: string;
+  submittedAt: string;
+  dismissedAt: string | null;
+  user: IPublicUser;
+}
+
+export interface IPublicPullRequestReviewComment {
+  id: number;
+  reviewId: number;
+  body: string;
+  path: string;
+  side: TRepositoryPullRequestReviewSide;
+  line: number;
+  commitId: string;
+  stale: boolean;
+  htmlUrl: string;
+  createdAt: string;
+  updatedAt: string;
+  user: IPublicUser;
+}
+
 export interface IPublicCommit {
   sha: string;
   shortSha: string;

package/ts/data/runner.ts

@@ -5,6 +5,7 @@ export type TOciRuntime = 'docker' | 'podman';
 export type TJobNetwork = 'none' | 'bridge';
 export type TLogStream = 'stdout' | 'stderr' | 'runner';
 export type TJobArtifactWhen = 'always' | 'success' | 'failure';
+export type TJobCacheSaveWhen = 'always' | 'success';
 export type TJobCompletionStatus =
   | 'succeeded'
   | 'failed'
@@ -25,7 +26,7 @@ export interface IRunnerCapabilities {
   networks: TJobNetwork[];
   sourceArchives: ['tar.gz'];
   artifacts: boolean;
-  caches: false;
+  caches: boolean;
   serviceContainers: false;
 }
 
@@ -89,6 +90,14 @@ export interface IJobArtifactSpec {
   retentionDays?: number;
 }
 
+export interface IJobCacheSpec {
+  name: string;
+  key: string;
+  paths: string[];
+  saveWhen?: TJobCacheSaveWhen;
+  retentionDays?: number;
+}
+
 export interface IJobSpec {
   image: string;
   command: string[];
@@ -99,6 +108,7 @@ export interface IJobSpec {
   resources?: IJobResources;
   source?: IJobSourceArchive;
   artifacts?: IJobArtifactSpec[];
+  caches?: IJobCacheSpec[];
 }
 
 export interface IJobLease {
@@ -162,6 +172,17 @@ export interface ICiArtifactUploadResponse {
   expiresAt: string;
 }
 
+export interface ICiCacheSaveResponse {
+  name: string;
+  key: string;
+  generation: number;
+  sha256: string;
+  sizeBytes: number;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+}
+
 export interface ICompleteJobRequest extends IJobMutationIdentity {
   status: TJobCompletionStatus;
   exitCode: number | null;

package/ts/requests/public.ts

@@ -62,6 +62,7 @@ export interface IReq_PublicRepo
     repo: string;
     path?: string;
     issueNumber?: number;
+    pullRequestNumber?: number;
   };
   response: {
     repo: data.IPublicRepo | null;
@@ -72,6 +73,11 @@ export interface IReq_PublicRepo
     issues: data.IPublicIssue[];
     selectedIssue: data.IPublicIssue | null;
     selectedIssueComments: data.IPublicIssueComment[];
+    pullRequests: data.IPublicPullRequest[];
+    selectedPullRequest: data.IPublicPullRequest | null;
+    selectedPullRequestComments: data.IPublicPullRequestComment[];
+    selectedPullRequestReviews: data.IPublicPullRequestReview[];
+    selectedPullRequestReviewComments: data.IPublicPullRequestReviewComment[];
     commits: data.IPublicCommit[];
     languages: Record<string, number>;
   };
@@ -235,3 +241,150 @@ export interface IReq_RepositoryIssueStateUpdate
     issue: data.IPublicIssue;
   };
 }
+
+export interface IReq_RepositoryPullRequestCreate
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestCreate
+  > {
+  method: 'repositoryPullRequestCreate';
+  request: {
+    org: string;
+    repo: string;
+    title: string;
+    body: string;
+    sourceOrg: string;
+    sourceRepo: string;
+    sourceRef: string;
+    targetRef: string;
+    draft: boolean;
+    accessToken: string;
+  };
+  response: {
+    pullRequest: data.IPublicPullRequest;
+  };
+}
+
+export interface IReq_RepositoryPullRequestCommentCreate
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestCommentCreate
+  > {
+  method: 'repositoryPullRequestCommentCreate';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    body: string;
+    accessToken: string;
+  };
+  response: {
+    comment: data.IPublicPullRequestComment;
+  };
+}
+
+export interface IReq_RepositoryPullRequestStateUpdate
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestStateUpdate
+  > {
+  method: 'repositoryPullRequestStateUpdate';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    state: 'open' | 'closed';
+    draft?: boolean;
+    accessToken: string;
+  };
+  response: {
+    pullRequest: data.IPublicPullRequest;
+  };
+}
+
+export interface IRepositoryPullRequestReviewCommentInput {
+  body: string;
+  path: string;
+  side: data.TRepositoryPullRequestReviewSide;
+  line: number;
+}
+
+export interface IReq_RepositoryPullRequestReviewSubmit
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestReviewSubmit
+  > {
+  method: 'repositoryPullRequestReviewSubmit';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    state: Exclude<data.TRepositoryPullRequestReviewState, 'dismissed'>;
+    body: string;
+    commitId: string;
+    comments: IRepositoryPullRequestReviewCommentInput[];
+    accessToken: string;
+  };
+  response: {
+    review: data.IPublicPullRequestReview;
+    comments: data.IPublicPullRequestReviewComment[];
+    pullRequest: data.IPublicPullRequest;
+  };
+}
+
+export interface IReq_RepositoryPullRequestReviewDismiss
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestReviewDismiss
+  > {
+  method: 'repositoryPullRequestReviewDismiss';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    reviewId: number;
+    message: string;
+    accessToken: string;
+  };
+  response: {
+    review: data.IPublicPullRequestReview;
+    pullRequest: data.IPublicPullRequest;
+  };
+}
+
+export interface IReq_RepositoryPullRequestMergeEnqueue
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestMergeEnqueue
+  > {
+  method: 'repositoryPullRequestMergeEnqueue';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    method: data.TRepositoryPullRequestMergeMethod;
+    expectedSourceObjectId: string;
+    expectedTargetObjectId: string;
+    accessToken: string;
+  };
+  response: {
+    pullRequest: data.IPublicPullRequest;
+  };
+}
+
+export interface IReq_RepositoryPullRequestMergeCancel
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_RepositoryPullRequestMergeCancel
+  > {
+  method: 'repositoryPullRequestMergeCancel';
+  request: {
+    org: string;
+    repo: string;
+    pullRequestNumber: number;
+    accessToken: string;
+  };
+  response: {
+    pullRequest: data.IPublicPullRequest;
+  };
+}