@rolino/contracts 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @rolino/contracts
 
+## 0.8.0
+
+### Minor Changes
+
+- 4e123ef: Add exact storage usage, bounded workspace media listing with required project context, and entitlement-checked, confirmation-bound Media Library cleanup across the shared contracts, SDK, and MCP tools. Cleanup status now reports a safe changed-asset skip when the confirmed workspace, project, storage identity, or asset version no longer matches.
+
+## 0.7.1
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -3,10 +3,18 @@
 The package includes strict shared backlink prospecting schemas for bounded targets, discoveries, prospects, score evidence, stages, public contacts, outreach drafts, and exact-link verification. The independent `backlinks:read`, `backlinks:write`, and `backlinks:contacts` capabilities do not widen existing credentials.
 
 Zod schemas and TypeScript types for Rolino's versioned public API. This package
-contains transport-safe DTOs only; it must not depend on Prisma, Next.js, auth
-providers, or server implementation details.
+contains transport-safe DTOs only; it must not depend on Prisma, Next.js, auth
+providers, or server implementation details.
+
+Storage-management contracts add the independent optional `storage:read` and
+`media:delete` capabilities, exact workspace usage, bounded project or workspace
+media lists, and confirmation-bound cleanup preview, execute, and status DTOs.
+Cleanup selections contain at most 500 candidates. Public DTOs omit storage keys,
+provider errors, credentials, and internal queue records.
+Workspace media items always include their project ID and project name. Media
+cursors are opaque deployment-time pagination state and are not long-term IDs.
 
-Contract 0.15 covers discovery, identity, capabilities, project reads and
+Contract 0.19 covers discovery, identity, capabilities, project reads and
 idempotent project creation, safe post and calendar reads, idempotent draft
 writes, and server-confirmed Instagram, TikTok, YouTube, Bluesky, and LinkedIn scheduling
 and immediate publishing. YouTube additions include explicit draft settings,

package/dist/index.cjs

@@ -182,6 +182,7 @@ __export(index_exports, {
   IntegrationHealthListResponseSchema: () => IntegrationHealthListResponseSchema,
   IntegrationHealthSchema: () => IntegrationHealthSchema,
   LinkedInDeliveryOptionsSchema: () => LinkedInDeliveryOptionsSchema,
+  ListedMediaAssetSchema: () => ListedMediaAssetSchema,
   MediaAssetListDataSchema: () => MediaAssetListDataSchema,
   MediaAssetListQuerySchema: () => MediaAssetListQuerySchema,
   MediaAssetListResponseSchema: () => MediaAssetListResponseSchema,
@@ -191,6 +192,22 @@ __export(index_exports, {
   MediaAssetUploadInputSchema: () => MediaAssetUploadInputSchema,
   MediaAssetUploadPreparationResponseSchema: () => MediaAssetUploadPreparationResponseSchema,
   MediaAssetUploadPreparationSchema: () => MediaAssetUploadPreparationSchema,
+  MediaCleanupCandidateSchema: () => MediaCleanupCandidateSchema,
+  MediaCleanupExecuteRequestSchema: () => MediaCleanupExecuteRequestSchema,
+  MediaCleanupExecuteResponseSchema: () => MediaCleanupExecuteResponseSchema,
+  MediaCleanupExecuteResultSchema: () => MediaCleanupExecuteResultSchema,
+  MediaCleanupItemResultSchema: () => MediaCleanupItemResultSchema,
+  MediaCleanupItemStatusSchema: () => MediaCleanupItemStatusSchema,
+  MediaCleanupOperationStatusSchema: () => MediaCleanupOperationStatusSchema,
+  MediaCleanupPreviewRequestSchema: () => MediaCleanupPreviewRequestSchema,
+  MediaCleanupPreviewResponseSchema: () => MediaCleanupPreviewResponseSchema,
+  MediaCleanupPreviewSchema: () => MediaCleanupPreviewSchema,
+  MediaCleanupScopeSchema: () => MediaCleanupScopeSchema,
+  MediaCleanupSelectionInputSchema: () => MediaCleanupSelectionInputSchema,
+  MediaCleanupStatusQuerySchema: () => MediaCleanupStatusQuerySchema,
+  MediaCleanupStatusResponseSchema: () => MediaCleanupStatusResponseSchema,
+  MediaCleanupStatusSchema: () => MediaCleanupStatusSchema,
+  NormalizedMediaCleanupSelectionSchema: () => NormalizedMediaCleanupSelectionSchema,
   PUBLISHING_PROVIDER_COUNT: () => PUBLISHING_PROVIDER_COUNT,
   PlatformPostStatusSchema: () => PlatformPostStatusSchema,
   PostDeliveryModeSchema: () => PostDeliveryModeSchema,
@@ -263,17 +280,25 @@ __export(index_exports, {
   SeoSearchIntentSchema: () => SeoSearchIntentSchema,
   SeoTaskDecisionSchema: () => SeoTaskDecisionSchema,
   SeoTaskFormatSchema: () => SeoTaskFormatSchema,
+  StorageByteCountSchema: () => StorageByteCountSchema,
+  StorageSourceBreakdownSchema: () => StorageSourceBreakdownSchema,
+  StorageUsageResponseSchema: () => StorageUsageResponseSchema,
+  StorageUsageSchema: () => StorageUsageSchema,
   TikTokDeliveryOptionsSchema: () => TikTokDeliveryOptionsSchema,
   TikTokDraftSettingsSchema: () => TikTokDraftSettingsSchema,
   TikTokPostSettingsSchema: () => TikTokPostSettingsSchema,
   WhoAmIResponseSchema: () => WhoAmIResponseSchema,
+  WorkspaceListedMediaAssetSchema: () => WorkspaceListedMediaAssetSchema,
+  WorkspaceMediaAssetListDataSchema: () => WorkspaceMediaAssetListDataSchema,
+  WorkspaceMediaAssetListQuerySchema: () => WorkspaceMediaAssetListQuerySchema,
+  WorkspaceMediaAssetListResponseSchema: () => WorkspaceMediaAssetListResponseSchema,
   YouTubePostSettingsSchema: () => YouTubePostSettingsSchema,
   successEnvelopeSchema: () => successEnvelopeSchema
 });
 module.exports = __toCommonJS(index_exports);
 var import_zod = require("zod");
 var API_VERSION = "v1";
-var CONTRACT_VERSION = "0.18.0";
+var CONTRACT_VERSION = "0.19.0";
 var RequestMetadataSchema = import_zod.z.object({
   requestId: import_zod.z.string().min(1)
 });
@@ -364,6 +389,8 @@ var CapabilityIdSchema = import_zod.z.enum([
   "posts:write",
   "posts:schedule",
   "posts:publish",
+  "storage:read",
+  "media:delete",
   "integrations:read",
   "calendar:read",
   "seo:read",
@@ -1064,22 +1091,49 @@ var MediaAssetSchema = import_zod.z.object({
   width: import_zod.z.number().int().positive().nullable(),
   height: import_zod.z.number().int().positive().nullable(),
   durationMs: import_zod.z.number().int().nonnegative().nullable(),
-  createdAt: import_zod.z.string().datetime()
+  createdAt: import_zod.z.string().datetime(),
+  usageCount: import_zod.z.number().int().nonnegative().optional(),
+  deletable: import_zod.z.boolean().optional(),
+  blockedReason: import_zod.z.enum(["IN_USE"]).nullable().optional(),
+  projectId: import_zod.z.string().min(1).optional(),
+  projectName: import_zod.z.string().min(1).max(200).optional()
 });
+var ListedMediaAssetSchema = MediaAssetSchema.extend({
+  usageCount: import_zod.z.number().int().nonnegative(),
+  deletable: import_zod.z.boolean(),
+  blockedReason: import_zod.z.enum(["IN_USE"]).nullable()
+});
+var WorkspaceListedMediaAssetSchema = ListedMediaAssetSchema.extend({
+  projectId: import_zod.z.string().min(1),
+  projectName: import_zod.z.string().min(1).max(200)
+});
+var OptionalBooleanQuerySchema = import_zod.z.union([
+  import_zod.z.boolean(),
+  import_zod.z.enum(["true", "false"]).transform((value) => value === "true")
+]);
 var MediaAssetListQuerySchema = import_zod.z.object({
   limit: import_zod.z.coerce.number().int().min(1).max(100).default(50),
-  cursor: import_zod.z.string().min(1).optional(),
+  cursor: import_zod.z.string().min(1).max(2048).optional(),
   type: import_zod.z.enum(["IMAGE", "VIDEO"]).optional(),
-  query: import_zod.z.string().trim().min(1).max(100).optional()
+  query: import_zod.z.string().trim().min(1).max(100).optional(),
+  createdBefore: import_zod.z.string().datetime({ offset: true }).optional(),
+  createdAfter: import_zod.z.string().datetime({ offset: true }).optional(),
+  unusedOnly: OptionalBooleanQuerySchema.optional(),
+  order: import_zod.z.enum(["OLDEST_FIRST", "NEWEST_FIRST"]).default("NEWEST_FIRST")
 });
+var WorkspaceMediaAssetListQuerySchema = MediaAssetListQuerySchema;
 var MediaAssetListDataSchema = import_zod.z.object({
-  items: import_zod.z.array(MediaAssetSchema),
+  items: import_zod.z.array(ListedMediaAssetSchema),
   page: import_zod.z.object({
     limit: import_zod.z.number().int().min(1).max(100),
     nextCursor: import_zod.z.string().min(1).nullable()
   })
 });
 var MediaAssetListResponseSchema = successEnvelopeSchema(MediaAssetListDataSchema);
+var WorkspaceMediaAssetListDataSchema = MediaAssetListDataSchema.extend({
+  items: import_zod.z.array(WorkspaceListedMediaAssetSchema)
+});
+var WorkspaceMediaAssetListResponseSchema = successEnvelopeSchema(WorkspaceMediaAssetListDataSchema);
 var MediaAssetUploadInputSchema = import_zod.z.object({
   fileName: import_zod.z.string().trim().min(1).max(255),
   contentType: import_zod.z.string().trim().min(1).max(100),
@@ -1100,6 +1154,166 @@ var MediaAssetUploadCompleteInputSchema = MediaAssetUploadInputSchema.extend({
   durationMs: import_zod.z.number().int().nonnegative().max(864e5).nullable().optional()
 }).strict();
 var MediaAssetResponseSchema = successEnvelopeSchema(MediaAssetSchema);
+var StorageByteCountSchema = import_zod.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var StorageSourceBreakdownSchema = import_zod.z.object({
+  mediaLibraryOriginalBytes: StorageByteCountSchema,
+  transformedSocialMediaBytes: StorageByteCountSchema,
+  blogImageBytes: StorageByteCountSchema,
+  detachedPendingDeletionBytes: StorageByteCountSchema
+});
+var StorageUsageSchema = import_zod.z.object({
+  storedBytes: StorageByteCountSchema,
+  reservedUploadBytes: StorageByteCountSchema,
+  uploadCommittedBytes: StorageByteCountSchema,
+  limitBytes: StorageByteCountSchema.nullable(),
+  availableUploadBytes: StorageByteCountSchema.nullable(),
+  storedPercent: import_zod.z.number().finite().nonnegative().nullable(),
+  uploadCommittedPercent: import_zod.z.number().finite().nonnegative().nullable(),
+  unlimited: import_zod.z.boolean(),
+  pendingDeletionBytes: StorageByteCountSchema,
+  sources: StorageSourceBreakdownSchema,
+  measuredAt: import_zod.z.string().datetime()
+});
+var StorageUsageResponseSchema = successEnvelopeSchema(StorageUsageSchema);
+var MediaCleanupScopeSchema = import_zod.z.discriminatedUnion("type", [
+  import_zod.z.object({ type: import_zod.z.literal("PROJECT"), projectId: import_zod.z.string().min(1).max(200) }).strict(),
+  import_zod.z.object({ type: import_zod.z.literal("WORKSPACE") }).strict()
+]);
+var MediaCleanupAssetIdsSchema = import_zod.z.array(import_zod.z.string().min(1).max(200)).min(1).max(100).superRefine((ids, context) => {
+  if (new Set(ids).size !== ids.length) {
+    context.addIssue({ code: "custom", message: "Asset IDs must be unique." });
+  }
+});
+var MediaCleanupSelectionInputSchema = import_zod.z.discriminatedUnion("mode", [
+  import_zod.z.object({
+    mode: import_zod.z.literal("ASSET_IDS"),
+    scope: MediaCleanupScopeSchema,
+    assetIds: MediaCleanupAssetIdsSchema
+  }).strict(),
+  import_zod.z.object({
+    mode: import_zod.z.literal("FILTER"),
+    scope: MediaCleanupScopeSchema,
+    createdBefore: import_zod.z.string().datetime({ offset: true }).optional(),
+    olderThanDays: import_zod.z.number().int().min(1).max(3650).optional(),
+    type: import_zod.z.enum(["IMAGE", "VIDEO"]).optional(),
+    query: import_zod.z.string().trim().min(1).max(100).optional()
+  }).strict().superRefine((selection, context) => {
+    if (Number(Boolean(selection.createdBefore)) + Number(selection.olderThanDays !== void 0) !== 1) {
+      context.addIssue({ code: "custom", message: "Choose exactly one upload-age filter." });
+    }
+  })
+]);
+var NormalizedMediaCleanupSelectionSchema = import_zod.z.discriminatedUnion("mode", [
+  import_zod.z.object({
+    mode: import_zod.z.literal("ASSET_IDS"),
+    scope: MediaCleanupScopeSchema,
+    assetIds: MediaCleanupAssetIdsSchema
+  }).strict(),
+  import_zod.z.object({
+    mode: import_zod.z.literal("FILTER"),
+    scope: MediaCleanupScopeSchema,
+    createdBefore: import_zod.z.string().datetime({ offset: true }),
+    type: import_zod.z.enum(["IMAGE", "VIDEO"]).optional(),
+    query: import_zod.z.string().trim().min(1).max(100).optional()
+  }).strict()
+]);
+var MediaCleanupPreviewRequestSchema = import_zod.z.object({
+  selection: MediaCleanupSelectionInputSchema
+}).strict();
+var MediaCleanupCandidateSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  fileName: import_zod.z.string().min(1).max(255).nullable(),
+  projectId: import_zod.z.string().min(1),
+  projectName: import_zod.z.string().min(1).max(200),
+  type: import_zod.z.enum(["IMAGE", "VIDEO"]),
+  createdAt: import_zod.z.string().datetime(),
+  sizeBytes: StorageByteCountSchema.nullable()
+});
+var MediaCleanupPreviewSchema = import_zod.z.object({
+  selection: NormalizedMediaCleanupSelectionSchema,
+  cutoffAt: import_zod.z.string().datetime().nullable(),
+  candidateCount: import_zod.z.number().int().min(0).max(500),
+  candidateIds: import_zod.z.array(import_zod.z.string().min(1)).max(500),
+  candidates: import_zod.z.array(MediaCleanupCandidateSchema).max(500),
+  estimatedReclaimableBytes: StorageByteCountSchema,
+  excludedInUseCount: import_zod.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  excludedInUseBytes: StorageByteCountSchema,
+  unknownSizeCount: import_zod.z.number().int().min(0).max(500),
+  hasMore: import_zod.z.boolean(),
+  candidateDigest: import_zod.z.string().regex(/^[a-f0-9]{64}$/),
+  confirmation: import_zod.z.object({
+    token: import_zod.z.string().min(1).max(500),
+    expiresAt: import_zod.z.string().datetime()
+  })
+});
+var MediaCleanupPreviewResponseSchema = successEnvelopeSchema(MediaCleanupPreviewSchema);
+var MediaCleanupExecuteRequestSchema = import_zod.z.object({
+  selection: NormalizedMediaCleanupSelectionSchema,
+  candidateDigest: import_zod.z.string().regex(/^[a-f0-9]{64}$/),
+  confirmationToken: import_zod.z.string().min(1).max(500)
+}).strict();
+var MediaCleanupOperationStatusSchema = import_zod.z.enum([
+  "QUEUED",
+  "RUNNING",
+  "COMPLETED",
+  "COMPLETED_WITH_SKIPS"
+]);
+var MediaCleanupItemStatusSchema = import_zod.z.enum([
+  "QUEUED",
+  "RETRYING",
+  "SKIPPED_IN_USE",
+  "SKIPPED_CHANGED",
+  "DELETED"
+]);
+var MediaCleanupExecuteResultSchema = import_zod.z.object({
+  cleanupId: import_zod.z.string().min(1),
+  status: MediaCleanupOperationStatusSchema,
+  candidateCount: import_zod.z.number().int().min(0).max(500),
+  queuedCount: import_zod.z.number().int().min(0).max(500),
+  skippedCount: import_zod.z.number().int().min(0).max(500),
+  estimatedReclaimableBytes: StorageByteCountSchema
+});
+var MediaCleanupExecuteResponseSchema = successEnvelopeSchema(MediaCleanupExecuteResultSchema);
+var MediaCleanupStatusQuerySchema = import_zod.z.object({
+  limit: import_zod.z.coerce.number().int().min(1).max(100).default(50),
+  cursor: import_zod.z.string().min(1).max(2048).optional()
+});
+var MediaCleanupItemResultSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  assetId: import_zod.z.string().min(1),
+  fileName: import_zod.z.string().min(1).max(255).nullable(),
+  projectId: import_zod.z.string().min(1),
+  projectName: import_zod.z.string().min(1).max(200),
+  type: import_zod.z.enum(["IMAGE", "VIDEO"]),
+  sizeBytes: StorageByteCountSchema.nullable(),
+  status: MediaCleanupItemStatusSchema,
+  queuedAt: import_zod.z.string().datetime().nullable(),
+  retryingAt: import_zod.z.string().datetime().nullable(),
+  skippedAt: import_zod.z.string().datetime().nullable(),
+  deletedAt: import_zod.z.string().datetime().nullable(),
+  failureSummary: import_zod.z.string().min(1).max(500).nullable()
+});
+var MediaCleanupStatusSchema = import_zod.z.object({
+  cleanupId: import_zod.z.string().min(1),
+  status: MediaCleanupOperationStatusSchema,
+  candidateCount: import_zod.z.number().int().min(0).max(500),
+  queuedCount: import_zod.z.number().int().min(0).max(500),
+  retryingCount: import_zod.z.number().int().min(0).max(500),
+  skippedCount: import_zod.z.number().int().min(0).max(500),
+  deletedCount: import_zod.z.number().int().min(0).max(500),
+  unknownSizeCount: import_zod.z.number().int().min(0).max(500),
+  estimatedReclaimableBytes: StorageByteCountSchema,
+  actualReleasedBytes: StorageByteCountSchema,
+  createdAt: import_zod.z.string().datetime(),
+  startedAt: import_zod.z.string().datetime().nullable(),
+  completedAt: import_zod.z.string().datetime().nullable(),
+  items: import_zod.z.array(MediaCleanupItemResultSchema).max(100),
+  page: import_zod.z.object({
+    limit: import_zod.z.number().int().min(1).max(100),
+    nextCursor: import_zod.z.string().min(1).max(2048).nullable()
+  })
+});
+var MediaCleanupStatusResponseSchema = successEnvelopeSchema(MediaCleanupStatusSchema);
 var PublishingProviderSchema = import_zod.z.enum([
   "INSTAGRAM",
   "TIKTOK",
@@ -2237,6 +2451,7 @@ var BacklinkContactListResponseSchema = successEnvelopeSchema(BacklinkContactLis
   IntegrationHealthListResponseSchema,
   IntegrationHealthSchema,
   LinkedInDeliveryOptionsSchema,
+  ListedMediaAssetSchema,
   MediaAssetListDataSchema,
   MediaAssetListQuerySchema,
   MediaAssetListResponseSchema,
@@ -2246,6 +2461,22 @@ var BacklinkContactListResponseSchema = successEnvelopeSchema(BacklinkContactLis
   MediaAssetUploadInputSchema,
   MediaAssetUploadPreparationResponseSchema,
   MediaAssetUploadPreparationSchema,
+  MediaCleanupCandidateSchema,
+  MediaCleanupExecuteRequestSchema,
+  MediaCleanupExecuteResponseSchema,
+  MediaCleanupExecuteResultSchema,
+  MediaCleanupItemResultSchema,
+  MediaCleanupItemStatusSchema,
+  MediaCleanupOperationStatusSchema,
+  MediaCleanupPreviewRequestSchema,
+  MediaCleanupPreviewResponseSchema,
+  MediaCleanupPreviewSchema,
+  MediaCleanupScopeSchema,
+  MediaCleanupSelectionInputSchema,
+  MediaCleanupStatusQuerySchema,
+  MediaCleanupStatusResponseSchema,
+  MediaCleanupStatusSchema,
+  NormalizedMediaCleanupSelectionSchema,
   PUBLISHING_PROVIDER_COUNT,
   PlatformPostStatusSchema,
   PostDeliveryModeSchema,
@@ -2318,10 +2549,18 @@ var BacklinkContactListResponseSchema = successEnvelopeSchema(BacklinkContactLis
   SeoSearchIntentSchema,
   SeoTaskDecisionSchema,
   SeoTaskFormatSchema,
+  StorageByteCountSchema,
+  StorageSourceBreakdownSchema,
+  StorageUsageResponseSchema,
+  StorageUsageSchema,
   TikTokDeliveryOptionsSchema,
   TikTokDraftSettingsSchema,
   TikTokPostSettingsSchema,
   WhoAmIResponseSchema,
+  WorkspaceListedMediaAssetSchema,
+  WorkspaceMediaAssetListDataSchema,
+  WorkspaceMediaAssetListQuerySchema,
+  WorkspaceMediaAssetListResponseSchema,
   YouTubePostSettingsSchema,
   successEnvelopeSchema
 });