@claudian-collab/protocol 3.2.0 → 3.2.1

package/dist/esm/CollabProjectRetirement.mjs

@@ -0,0 +1,119 @@
+import { CollabError } from './CollabError.mjs';
+import { isCollabGitOid, isCollabOpaqueId, isCollabProjectId, } from './CollabValidation.mjs';
+export const COLLAB_PROJECT_RETIREMENT_RESULT_KINDS = Object.freeze([
+    'project-retired',
+]);
+export const COLLAB_PROJECT_RETIREMENT_OPERATIONS = Object.freeze([
+    'retireProject',
+    'acknowledgeProjectRetirement',
+]);
+function invalidPayload(field) {
+    return new CollabError({ code: 'protocol-payload-invalid', safeContext: { field } });
+}
+function exactRecord(value, field, keys) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalidPayload(field);
+    }
+    const source = value;
+    const expected = new Set(keys);
+    if (!keys.every(key => Object.hasOwn(source, key))
+        || Object.keys(source).some(key => !expected.has(key)))
+        throw invalidPayload(field);
+    return source;
+}
+function token(source, field, validate = isCollabOpaqueId) {
+    const value = source[field];
+    if (typeof value !== 'string' || !validate(value))
+        throw invalidPayload(field);
+    return value;
+}
+function positiveInteger(source, field) {
+    const value = source[field];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+        throw invalidPayload(field);
+    }
+    return value;
+}
+function timestamp(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string'
+        || value.length > 64
+        || Number.isNaN(Date.parse(value))
+        || new Date(value).toISOString() !== value)
+        throw invalidPayload(field);
+    return value;
+}
+export function decodeCollabProjectRetirementRequest(value) {
+    const source = exactRecord(value, 'retirementRequest', [
+        'expectedAuthorityGeneration',
+        'expectedMainOid',
+        'idempotencyKey',
+        'projectId',
+    ]);
+    return {
+        expectedAuthorityGeneration: positiveInteger(source, 'expectedAuthorityGeneration'),
+        expectedMainOid: token(source, 'expectedMainOid', isCollabGitOid),
+        idempotencyKey: token(source, 'idempotencyKey'),
+        projectId: token(source, 'projectId', isCollabProjectId),
+    };
+}
+export function decodeCollabProjectRetirementResult(value) {
+    const source = exactRecord(value, 'retirementResult', [
+        'acknowledgementRequired',
+        'kind',
+        'projectId',
+        'retiredAt',
+        'retirementId',
+        'terminalExpiresAt',
+    ]);
+    if (source.acknowledgementRequired !== true || source.kind !== 'project-retired') {
+        throw invalidPayload('retirementResult');
+    }
+    const retiredAt = timestamp(source, 'retiredAt');
+    const terminalExpiresAt = timestamp(source, 'terminalExpiresAt');
+    if (Date.parse(terminalExpiresAt) <= Date.parse(retiredAt)) {
+        throw invalidPayload('terminalExpiresAt');
+    }
+    return {
+        acknowledgementRequired: true,
+        kind: 'project-retired',
+        projectId: token(source, 'projectId', isCollabProjectId),
+        retiredAt,
+        retirementId: token(source, 'retirementId'),
+        terminalExpiresAt,
+    };
+}
+export function decodeCollabProjectRetirementAcknowledgement(value) {
+    const source = exactRecord(value, 'retirementAcknowledgement', [
+        'acknowledgedAt',
+        'idempotencyKey',
+        'projectId',
+        'retirementId',
+    ]);
+    return {
+        acknowledgedAt: timestamp(source, 'acknowledgedAt'),
+        idempotencyKey: token(source, 'idempotencyKey'),
+        projectId: token(source, 'projectId', isCollabProjectId),
+        retirementId: token(source, 'retirementId'),
+    };
+}
+export function decodeCollabProjectRetirementOperationRequest(operation, value) {
+    if (operation === 'retireProject') {
+        return decodeCollabProjectRetirementRequest(value);
+    }
+    const source = exactRecord(value, 'retirementAcknowledgementRequest', [
+        'idempotencyKey',
+        'projectId',
+        'retirementId',
+    ]);
+    return {
+        idempotencyKey: token(source, 'idempotencyKey'),
+        projectId: token(source, 'projectId', isCollabProjectId),
+        retirementId: token(source, 'retirementId'),
+    };
+}
+export function decodeCollabProjectRetirementOperationResponse(operation, value) {
+    return (operation === 'retireProject'
+        ? decodeCollabProjectRetirementResult(value)
+        : decodeCollabProjectRetirementAcknowledgement(value));
+}

package/dist/esm/CollabProtocol.mjs

@@ -0,0 +1,64 @@
+import { COLLAB_PROTOCOL_VERSION } from './CollabConstants.mjs';
+import { CollabError } from './CollabError.mjs';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(record, required) {
+    const allowed = new Set(required);
+    return required.every(key => Object.hasOwn(record, key))
+        && Object.keys(record).every(key => allowed.has(key));
+}
+function requiredString(record, field) {
+    const value = record[field];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function invalidPayload(field) {
+    return {
+        status: 'invalid',
+        error: new CollabError({
+            code: 'protocol-payload-invalid',
+            safeContext: { field },
+        }),
+    };
+}
+function unsupportedVersion(receivedVersion) {
+    return {
+        status: 'unsupported-version',
+        receivedVersion,
+        error: new CollabError({
+            code: 'protocol-version-unsupported',
+            safeContext: {
+                receivedVersion,
+                supportedVersion: COLLAB_PROTOCOL_VERSION,
+            },
+        }),
+    };
+}
+function decodeVersion(record) {
+    const version = record.protocolVersion;
+    if (typeof version !== 'number' || !Number.isInteger(version)) {
+        return invalidPayload('protocolVersion');
+    }
+    if (version !== COLLAB_PROTOCOL_VERSION)
+        return unsupportedVersion(version);
+    return { status: 'ok', value: COLLAB_PROTOCOL_VERSION };
+}
+export function decodeCollabProtocolEnvelope(input) {
+    if (!isRecord(input) || !hasExactKeys(input, ['protocolVersion', 'requestId', 'data'])) {
+        return invalidPayload('envelope');
+    }
+    const version = decodeVersion(input);
+    if (version.status !== 'ok')
+        return version;
+    const requestId = requiredString(input, 'requestId');
+    if (!requestId)
+        return invalidPayload('requestId');
+    return {
+        status: 'ok',
+        value: {
+            data: input.data,
+            protocolVersion: version.value,
+            requestId,
+        },
+    };
+}

package/dist/esm/CollabRequestTicketRequestCodecs.mjs

@@ -0,0 +1,263 @@
+import { COLLAB_LIMITS } from './CollabConstants.mjs';
+import { CollabError } from './CollabError.mjs';
+import { hasUtf8ByteLengthAtMost, isCollabGitOid, isCollabOpaqueId, isCollabProjectId, } from './CollabValidation.mjs';
+function invalid(reason) {
+    return {
+        error: new CollabError({
+            code: 'protocol-payload-invalid',
+            safeContext: { reason },
+        }),
+        status: 'invalid',
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return required.every(key => Object.hasOwn(value, key))
+        && Object.keys(value).every(key => allowed.has(key));
+}
+function isRevision(value, minimum = 0) {
+    return typeof value === 'number'
+        && Number.isSafeInteger(value)
+        && value >= minimum;
+}
+function isPageQuery(value, maxLimit = COLLAB_LIMITS.maxCommentPageSize) {
+    return (value.cursor === undefined
+        || (typeof value.cursor === 'string'
+            && value.cursor.length > 0
+            && value.cursor.length <= COLLAB_LIMITS.maxPageCursorUtf16))
+        && (value.limit === undefined
+            || (isRevision(value.limit, 1) && value.limit <= maxLimit));
+}
+function mutationContext(value) {
+    return isCollabProjectId(value.projectId) && isCollabOpaqueId(value.idempotencyKey);
+}
+function resolvingTickets(value) {
+    if (!Array.isArray(value) || value.length > COLLAB_LIMITS.maxRequestTicketRelations)
+        return null;
+    const seen = new Set();
+    const result = [];
+    for (const entry of value) {
+        if (!isRecord(entry)
+            || !isCollabOpaqueId(entry.ticketId)
+            || seen.has(entry.ticketId)
+            || !isRevision(entry.revision, 1))
+            return null;
+        seen.add(entry.ticketId);
+        result.push({ ticketId: entry.ticketId, revision: entry.revision });
+    }
+    return result;
+}
+function decodeRequestTicketRequest(operation, input) {
+    if (!isRecord(input))
+        return null;
+    switch (operation) {
+        case 'getRequest':
+            return isCollabProjectId(input.projectId) && isCollabOpaqueId(input.requestId)
+                ? { projectId: input.projectId, requestId: input.requestId }
+                : null;
+        case 'ensureMyRequest':
+            return mutationContext(input)
+                && isCollabGitOid(input.expectedMainOid)
+                && isCollabGitOid(input.headOid)
+                && typeof input.description === 'string'
+                && hasUtf8ByteLengthAtMost(input.description, COLLAB_LIMITS.maxRequestDescriptionBytes)
+                ? {
+                    description: input.description,
+                    expectedMainOid: input.expectedMainOid,
+                    headOid: input.headOid,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                }
+                : null;
+        case 'createComment':
+            return mutationContext(input)
+                && isCollabOpaqueId(input.requestId)
+                && typeof input.body === 'string'
+                && hasUtf8ByteLengthAtMost(input.body, COLLAB_LIMITS.maxCommentBytes)
+                && input.anchor === undefined
+                ? {
+                    body: input.body,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    requestId: input.requestId,
+                }
+                : null;
+        case 'updateMyRequestMetadata':
+            return mutationContext(input)
+                && isCollabOpaqueId(input.requestId)
+                && isCollabGitOid(input.expectedHeadOid)
+                && isRevision(input.expectedRequestRevision)
+                && typeof input.description === 'string'
+                && hasUtf8ByteLengthAtMost(input.description, COLLAB_LIMITS.maxRequestDescriptionBytes)
+                ? {
+                    description: input.description,
+                    expectedHeadOid: input.expectedHeadOid,
+                    expectedRequestRevision: input.expectedRequestRevision,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    requestId: input.requestId,
+                }
+                : null;
+        case 'acceptRequest': {
+            const expectedResolvingTickets = resolvingTickets(input.expectedResolvingTickets);
+            return mutationContext(input)
+                && isCollabOpaqueId(input.requestId)
+                && isCollabGitOid(input.expectedMainOid)
+                && isCollabGitOid(input.expectedHeadOid)
+                && isRevision(input.expectedRequestRevision)
+                && expectedResolvingTickets !== null
+                ? {
+                    expectedHeadOid: input.expectedHeadOid,
+                    expectedMainOid: input.expectedMainOid,
+                    expectedRequestRevision: input.expectedRequestRevision,
+                    expectedResolvingTickets,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    requestId: input.requestId,
+                }
+                : null;
+        }
+        case 'listTickets':
+            return hasExactKeys(input, ['projectId', 'status'], ['cursor', 'limit'])
+                && isCollabProjectId(input.projectId)
+                && (input.status === 'open' || input.status === 'closed' || input.status === 'all')
+                && isPageQuery(input, COLLAB_LIMITS.maxTicketPageSize)
+                ? {
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    projectId: input.projectId,
+                    status: input.status,
+                }
+                : null;
+        case 'listRequestComments':
+            return hasExactKeys(input, ['projectId', 'requestId'], ['cursor', 'limit'])
+                && isCollabProjectId(input.projectId)
+                && isCollabOpaqueId(input.requestId)
+                && isPageQuery(input)
+                ? {
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    projectId: input.projectId,
+                    requestId: input.requestId,
+                }
+                : null;
+        case 'listTicketComments':
+            return hasExactKeys(input, ['projectId', 'ticketId'], ['cursor', 'limit'])
+                && isCollabProjectId(input.projectId)
+                && isCollabOpaqueId(input.ticketId)
+                && isPageQuery(input)
+                ? {
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    projectId: input.projectId,
+                    ticketId: input.ticketId,
+                }
+                : null;
+        case 'listTicketAcceptedRelations':
+            return hasExactKeys(input, ['projectId', 'ticketId'], ['cursor', 'limit'])
+                && isCollabProjectId(input.projectId)
+                && isCollabOpaqueId(input.ticketId)
+                && isPageQuery(input, COLLAB_LIMITS.maxRelationsPerPage)
+                ? {
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    projectId: input.projectId,
+                    ticketId: input.ticketId,
+                }
+                : null;
+        case 'getTicket':
+            return hasExactKeys(input, ['projectId', 'ticketId'])
+                && isCollabProjectId(input.projectId)
+                && isCollabOpaqueId(input.ticketId)
+                ? { projectId: input.projectId, ticketId: input.ticketId }
+                : null;
+        case 'createTicket':
+            return hasExactKeys(input, ['body', 'idempotencyKey', 'projectId', 'title'])
+                && mutationContext(input)
+                && typeof input.body === 'string'
+                && typeof input.title === 'string'
+                && hasUtf8ByteLengthAtMost(input.body, COLLAB_LIMITS.maxTicketBodyBytes)
+                && input.title.length <= COLLAB_LIMITS.maxTicketTitleUtf16
+                ? {
+                    body: input.body,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    title: input.title,
+                }
+                : null;
+        case 'updateTicketContent':
+            return hasExactKeys(input, [
+                'body', 'expectedRevision', 'idempotencyKey', 'projectId', 'ticketId', 'title',
+            ])
+                && mutationContext(input)
+                && isCollabOpaqueId(input.ticketId)
+                && isRevision(input.expectedRevision, 1)
+                && typeof input.body === 'string'
+                && typeof input.title === 'string'
+                && hasUtf8ByteLengthAtMost(input.body, COLLAB_LIMITS.maxTicketBodyBytes)
+                && input.title.length <= COLLAB_LIMITS.maxTicketTitleUtf16
+                ? {
+                    body: input.body,
+                    expectedRevision: input.expectedRevision,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    ticketId: input.ticketId,
+                    title: input.title,
+                }
+                : null;
+        case 'createTicketComment':
+            return hasExactKeys(input, ['body', 'idempotencyKey', 'projectId', 'ticketId'])
+                && mutationContext(input)
+                && isCollabOpaqueId(input.ticketId)
+                && typeof input.body === 'string'
+                && hasUtf8ByteLengthAtMost(input.body, COLLAB_LIMITS.maxTicketCommentBytes)
+                ? {
+                    body: input.body,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    ticketId: input.ticketId,
+                }
+                : null;
+        case 'closeTicket':
+        case 'reopenTicket':
+            return hasExactKeys(input, [
+                'expectedRevision', 'idempotencyKey', 'projectId', 'ticketId',
+            ])
+                && mutationContext(input)
+                && isCollabOpaqueId(input.ticketId)
+                && isRevision(input.expectedRevision, 1)
+                ? {
+                    expectedRevision: input.expectedRevision,
+                    idempotencyKey: input.idempotencyKey,
+                    projectId: input.projectId,
+                    ticketId: input.ticketId,
+                }
+                : null;
+    }
+}
+const INVALID_REASONS = {
+    acceptRequest: 'request-accept-payload-invalid',
+    closeTicket: 'ticket-mutation-payload-invalid',
+    createComment: 'request-comment-payload-invalid',
+    createTicket: 'ticket-create-payload-invalid',
+    createTicketComment: 'ticket-comment-payload-invalid',
+    ensureMyRequest: 'request-ensure-payload-invalid',
+    getRequest: 'request-read-payload-invalid',
+    getTicket: 'ticket-read-payload-invalid',
+    listRequestComments: 'request-comment-page-query-invalid',
+    listTicketAcceptedRelations: 'ticket-relation-page-query-invalid',
+    listTicketComments: 'ticket-comment-page-query-invalid',
+    listTickets: 'ticket-list-query-invalid',
+    reopenTicket: 'ticket-mutation-payload-invalid',
+    updateMyRequestMetadata: 'request-metadata-payload-invalid',
+    updateTicketContent: 'ticket-content-payload-invalid',
+};
+export function decodeCollabRequestTicketOperationRequest(operation, input) {
+    const value = decodeRequestTicketRequest(operation, input);
+    return value
+        ? { status: 'ok', value: value }
+        : invalid(INVALID_REASONS[operation]);
+}