@publishq/sdk 0.0.1 → 0.0.2

package/README.md

@@ -40,7 +40,7 @@ for (const account of data?.accounts ?? []) {
 ## Authentication
 
 Pass your API key (starts with `pq_live_`). Create one in the PublishQ web app
-under **Settings → API Keys** and select the scopes you need.
+under **API Keys** and select the scopes you need.
 
 ```ts
 const publishq = new PublishQ({ apiKey: 'pq_live_...' });
@@ -95,7 +95,7 @@ await publishq.workspaces.get('<workspace-id>');
 ### Media
 
 ```ts
-// Upload a file, then attach the returned media id to a post via `mediaIds`
+// Upload a file of up to 4 GB, then attach the returned media id to a post via `mediaIds`.
 const { data: media } = await publishq.media.upload({ file });
 await publishq.media.list({ mediaTypes: ['IMAGE'] });
 await publishq.media.get('<media-id>');
@@ -114,7 +114,7 @@ returns `403`.
 | `workspaces:read`  | `workspaces.list`, `workspaces.get`     |
 | `workspaces:write` | `workspaces.create`                     |
 | `media:read`       | `media.list`, `media.get`               |
-| `media:write`      | `media.upload`                          |
+| `media:write`      | `media.upload`, `media.createUpload`, `media.completeUpload` |
 
 ## Configuration
 

package/dist/index.cjs

@@ -34,14 +34,21 @@ __export(index_exports, {
   Media2: () => Media,
   Posts: () => Posts,
   PublishQ: () => PublishQ,
+  STORAGE_UPLOAD_THRESHOLD_BYTES: () => STORAGE_UPLOAD_THRESHOLD_BYTES,
   Workspaces: () => Workspaces,
   default: () => index_default,
+  withInferredContentType: () => withInferredContentType,
   zAccount: () => zAccount,
   zAccountsResponse: () => zAccountsResponse,
   zApiError: () => zApiError,
   zApiErrorCode: () => zApiErrorCode,
   zApiKeyScope: () => zApiKeyScope,
   zBlueskyPlatformSpecificSettings: () => zBlueskyPlatformSpecificSettings,
+  zCompleteMediaUploadPath: () => zCompleteMediaUploadPath,
+  zCompleteMediaUploadResponse: () => zCompleteMediaUploadResponse,
+  zCreateMediaUploadBody: () => zCreateMediaUploadBody,
+  zCreateMediaUploadRequest: () => zCreateMediaUploadRequest,
+  zCreateMediaUploadResponse: () => zCreateMediaUploadResponse,
   zCreatePostAccount: () => zCreatePostAccount,
   zCreatePostBody: () => zCreatePostBody,
   zCreatePostRequest: () => zCreatePostRequest,
@@ -74,13 +81,17 @@ __export(index_exports, {
   zMediaListResponse: () => zMediaListResponse,
   zMediaSource: () => zMediaSource,
   zMediaType: () => zMediaType,
+  zMediaUpload: () => zMediaUpload,
   zPagination: () => zPagination,
   zPlatformSpecificSettings: () => zPlatformSpecificSettings,
   zPost: () => zPost,
   zPostAccount: () => zPostAccount,
+  zPostAnalytics: () => zPostAnalytics,
   zPostOverrides: () => zPostOverrides,
+  zPostSource: () => zPostSource,
   zPostStatus: () => zPostStatus,
   zPostsResponse: () => zPostsResponse,
+  zPublishFailure: () => zPublishFailure,
   zRemovePostAccountPath: () => zRemovePostAccountPath,
   zRemovePostAccountResponse: () => zRemovePostAccountResponse,
   zSocialPlatform: () => zSocialPlatform,
@@ -920,7 +931,7 @@ var Posts = class {
   /**
    * List posts
    *
-   * Returns a paginated list of posts.
+   * Returns a paginated list of the posts you created through PublishQ. Posts imported from a connected platform are excluded by default; pass includeImported=true to get both, or onlyImported=true for only the imported ones.
    */
   static listPosts(options) {
     return (options?.client ?? client).get({
@@ -1082,7 +1093,7 @@ var Media = class {
   /**
    * Upload media
    *
-   * Upload one media file with multipart form data. The returned media ID can then be attached to posts.
+   * Upload a file smaller than 100 MB in a single request. It is the simplest way to upload: one call returns a media ID you can attach to posts. For bigger files, use Create media upload.
    */
   static uploadMedia(options) {
     return (options.client ?? client).post({
@@ -1108,6 +1119,39 @@ var Media = class {
       ...options
     });
   }
+  /**
+   * Create media upload
+   *
+   * Upload a file of up to 4 GB (500 MB on the Free plan) straight to storage:
+   *
+   * 1. Call this endpoint with `filename`, `contentType` and `fileSize`. You get back an `id` and an `uploadUrl`.
+   * 2. `PUT` the file to `uploadUrl` with the same `Content-Type` header. Storage answers `200`, or `403` if the file is not exactly `fileSize` bytes.
+   * 3. Optional: call Complete media upload to add the file to your media library now.
+   * 4. Put the `id` in `mediaIds` when you create or update a post.
+   */
+  static createMediaUpload(options) {
+    return (options.client ?? client).post({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/media/uploads",
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+  }
+  /**
+   * Complete media upload
+   *
+   * Optional. Adds a file uploaded through Create media upload to your media library now and returns it. Without this call the file is added the first time you use its id in a post, and an upload nobody completes or uses within 1 day expires.
+   */
+  static completeMediaUpload(options) {
+    return (options.client ?? client).post({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/media/uploads/{id}/complete",
+      ...options
+    });
+  }
 };
 
 // src/generated/zod.gen.ts
@@ -1127,6 +1171,7 @@ var zApiErrorCode = z.enum([
   "post_not_editable",
   "media_not_found",
   "media_in_use",
+  "media_upload_incomplete",
   "storage_limit_exceeded",
   "free_media_limit_exceeded",
   "free_pending_media_limit_exceeded",
@@ -1137,6 +1182,9 @@ var zApiErrorCode = z.enum([
   "invalid_file_extension",
   "social_accounts_not_found",
   "social_accounts_expired",
+  "social_account_limit_exceeded",
+  "platform_temporarily_unavailable",
+  "platform_permission_missing",
   "platform_validation_failed",
   "posting_limits_exceeded",
   "scheduled_at_required",
@@ -1146,10 +1194,12 @@ var zApiErrorCode = z.enum([
   "workspace_not_found",
   "workspace_forbidden",
   "workspace_owner_required",
+  "workspace_limit_exceeded",
   "workspace_account_not_found",
   "workspace_account_conflict",
   "workspace_member_not_found",
   "workspace_member_conflict",
+  "team_member_limit_exceeded",
   "workspace_invitation_invalid",
   "workspace_invitation_expired"
 ]);
@@ -1358,6 +1408,56 @@ var zTwitterPlatformSpecificSettings = z.object({
 }).register(z.globalRegistry, {
   description: "X (Twitter) specific post settings. All fields are optional."
 });
+var zPostSource = z.enum(["PUBLISHQ", "IMPORTED"]).register(z.globalRegistry, {
+  description: "Where the post came from. PUBLISHQ: created in PublishQ. IMPORTED: published directly on the platform and discovered during an analytics sync, so the post history stays complete."
+});
+var zPostAnalytics = z.object({
+  views: z.int().check(z.gte(0)).register(z.globalRegistry, {
+    description: "Views the platform reports for this post."
+  }),
+  likes: z.int().check(z.gte(0)).register(z.globalRegistry, {
+    description: "Likes the platform reports for this post."
+  }),
+  comments: z.int().check(z.gte(0)).register(z.globalRegistry, {
+    description: "Comments the platform reports for this post."
+  }),
+  shares: z.int().check(z.gte(0)).register(z.globalRegistry, {
+    description: "Shares the platform reports for this post. 0 on platforms that do not disclose it (including YouTube)."
+  }),
+  extraMetrics: z.record(z.string(), z.int().check(z.gte(0))).register(z.globalRegistry, {
+    description: "Metrics only this platform reports, keyed by metric name \u2014 Bluesky bookmarks, for example. Every metric the platform reports is always present, 0 included, so no key has to be guessed. Empty on platforms that expose nothing beyond the fields above, and a metric that already has its own field is never repeated here."
+  }),
+  syncedAt: z.iso.datetime().register(z.globalRegistry, {
+    description: "When these numbers were last recorded. Metrics are refreshed in the background roughly once a day, and only stored when they change."
+  })
+});
+var zPublishFailure = z.object({
+  kind: z.enum([
+    "RECONNECT",
+    "MEDIA",
+    "ACCOUNT_STATE",
+    "TRANSIENT",
+    "MAYBE_PUBLISHED",
+    "UNKNOWN"
+  ]).register(z.globalRegistry, {
+    description: "What kind of action this failure needs. `RECONNECT`: the account has to be reconnected. `MEDIA`: the platform refused the attached file. `ACCOUNT_STATE`: the platform is blocking this account, so the fix is on the platform. `TRANSIENT`: the platform was unavailable and the same request can succeed unchanged. `MAYBE_PUBLISHED`: the platform reported an error for a post that may have gone out anyway. `UNKNOWN`: unrecognised, so read `errorMessage`."
+  }),
+  title: z.string().register(z.globalRegistry, {
+    description: "Short label for this failure."
+  }),
+  whatHappened: z.string().register(z.globalRegistry, {
+    description: "One sentence about what the platform did."
+  }),
+  whatToDo: z.string().register(z.globalRegistry, {
+    description: "One sentence naming the next action."
+  }),
+  canRetry: z.boolean().register(z.globalRegistry, {
+    description: "Whether retrying can succeed. False when the platform is blocking the account, since the same request will be refused the same way."
+  }),
+  checkPlatformFirst: z.boolean().register(z.globalRegistry, {
+    description: "Whether the post may already be live. A publish is not idempotent and no platform accepts a deduplication key, so when this is true a retry can create a second copy: check the profile before retrying."
+  })
+});
 var zSocialPlatform = z.enum([
   "TWITTER",
   "INSTAGRAM",
@@ -1382,8 +1482,8 @@ var zPostOverrides = z.object({
   thumbnailTimestamp: z.optional(z.int().check(z.gte(0)).register(z.globalRegistry, {
     description: "Video thumbnail timestamp in milliseconds. Applies to Instagram and TikTok."
   })),
-  mediaIds: z.optional(z.array(z.uuid()).register(z.globalRegistry, {
-    description: "Replacement media for this account. Completely replaces the post-level media."
+  mediaIds: z.optional(z.array(z.uuid()).check(z.maxLength(35)).register(z.globalRegistry, {
+    description: "Replacement media for this account. Completely replaces the post-level media. Up to 35."
   }))
 });
 var zPlatformSpecificSettings = z.union([
@@ -1575,6 +1675,12 @@ var zPostAccount = z.object({
   errorMessage: z.optional(z.string().register(z.globalRegistry, {
     description: "Error message from the platform if publishing failed for this account."
   })),
+  failure: z.optional(z.intersection(zPublishFailure, z.unknown().register(z.globalRegistry, {
+    description: "The same failure read as an action: what happened and the one thing to do about it. Present whenever status is FAILED, including when the platform gave no reason. The wording is what the app and the failure email show, so a client does not have to interpret `errorMessage` itself."
+  }))),
+  analytics: z.optional(z.intersection(zPostAnalytics, z.unknown().register(z.globalRegistry, {
+    description: "Latest metrics recorded for this delivery. Present only for published posts on platforms with analytics support, once a background sync has run."
+  }))),
   postOverrides: z.optional(zPostOverrides),
   platformSpecificSettings: z.optional(zPlatformSpecificSettings)
 });
@@ -1586,6 +1692,7 @@ var zPost = z.object({
     description: "The shared text content of the post."
   }),
   status: zPostStatus,
+  source: zPostSource,
   errorMessage: z.optional(z.string().register(z.globalRegistry, {
     description: "Human-readable error summary when one or more accounts failed."
   })),
@@ -1627,8 +1734,8 @@ var zCreatePostRequest = z.object({
   content: z._default(z.optional(z.string().register(z.globalRegistry, {
     description: "The text content of the post, shared across all accounts unless overridden. Optional when media is attached (platform-dependent)."
   })), ""),
-  mediaIds: z.optional(z.array(z.uuid()).register(z.globalRegistry, {
-    description: "Media to attach to the post. Shared across all accounts unless an account provides its own mediaIds in postOverrides."
+  mediaIds: z.optional(z.array(z.uuid()).check(z.maxLength(35)).register(z.globalRegistry, {
+    description: "Media to attach to the post, up to 35. Shared across all accounts unless an account provides its own mediaIds in postOverrides. Accepts IDs from Upload media and from Create media upload."
   })),
   thumbnailTimestamp: z.optional(z.int().check(z.gte(0)).register(z.globalRegistry, {
     description: "Default video thumbnail timestamp in milliseconds for Instagram and TikTok. Can be overridden per account."
@@ -1637,7 +1744,7 @@ var zCreatePostRequest = z.object({
     description: "Accounts to post to. Each entry can optionally include content overrides and platform-specific settings."
   }),
   scheduledAt: z.optional(z.iso.datetime().register(z.globalRegistry, {
-    description: "Schedule the post for a future date. If omitted and publishNow is false or absent, the post is saved as a draft."
+    description: "Schedule the post for a future date. If omitted and publishNow is false or absent, the post is saved as a draft. Accepts UTC (2026-04-01T12:00:00Z) or an explicit UTC offset (2026-04-01T14:00:00+02:00); a time without zone information is rejected."
   })),
   publishNow: z.optional(z.boolean().register(z.globalRegistry, {
     description: "Publish immediately. Cannot be combined with scheduledAt."
@@ -1650,10 +1757,10 @@ var zUpdatePostRequest = z.object({
     description: "New shared text content for the post."
   })),
   scheduledAt: z.optional(z.iso.datetime().register(z.globalRegistry, {
-    description: "New scheduled date for the post. Must be at least 1 minute in the future."
+    description: "New scheduled date for the post. Must be at least 1 minute in the future. Accepts UTC (2026-04-15T14:00:00Z) or an explicit UTC offset (2026-04-15T16:00:00+02:00); a time without zone information is rejected."
   })),
-  mediaIds: z.optional(z.array(z.uuid()).register(z.globalRegistry, {
-    description: "Full replacement for the post media. If omitted, the existing media stays unchanged. If provided, it replaces the current media across all accounts in the post. Send an empty array to remove all media from the post."
+  mediaIds: z.optional(z.array(z.uuid()).check(z.maxLength(35)).register(z.globalRegistry, {
+    description: "Full replacement for the post media, up to 35. If omitted, the existing media stays unchanged. If provided, it replaces the current media across all accounts in the post. Send an empty array to remove all media from the post."
   })),
   thumbnailTimestamp: z.optional(z.int().check(z.gte(0)).register(z.globalRegistry, {
     description: "New video thumbnail timestamp in milliseconds for Instagram and TikTok media. Does not change which media files are attached. Combine with mediaIds if you want to replace media and set the new thumbnail timestamp in the same request."
@@ -1762,6 +1869,28 @@ var zMediaListResponse = z.object({
 var zUploadMediaRequest = z.object({
   file: z.string()
 });
+var zCreateMediaUploadRequest = z.object({
+  filename: z.string().check(z.minLength(1), z.maxLength(1024)).register(z.globalRegistry, {
+    description: "Name of the file you are uploading."
+  }),
+  contentType: z.string().check(z.minLength(1)).register(z.globalRegistry, {
+    description: "Content type of the file. One of: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/webm, video/quicktime, video/x-msvideo."
+  }),
+  fileSize: z.int().check(z.gt(0)).register(z.globalRegistry, {
+    description: "Exact size of the file in bytes. Your plan's file size limit and your storage are checked before you upload, and storage refuses a file of any other size. Each platform's own size limits are checked when you attach the media to a post."
+  })
+});
+var zMediaUpload = z.object({
+  id: z.uuid().register(z.globalRegistry, {
+    description: "Media ID of the file. Attach it to posts through mediaIds once the file is uploaded."
+  }),
+  uploadUrl: z.url().register(z.globalRegistry, {
+    description: "Signed storage URL. PUT the file to it with the same Content-Type. It goes to storage, not to the PublishQ API, so send no Authorization header."
+  }),
+  expiresAt: z.iso.datetime().register(z.globalRegistry, {
+    description: "When uploadUrl stops accepting the file, 1 hour after it is created."
+  })
+});
 var zTikTokCreatorInfoResponse = z.object({
   privacyLevelOptions: z.array(z.string()).register(z.globalRegistry, {
     description: "Privacy levels available for this account. Use one of these values as `privacyLevel` in `platformSpecificSettings`."
@@ -1794,7 +1923,13 @@ var zListPostsQuery = z.object({
   })), 1),
   limit: z._default(z.optional(z.int().check(z.gt(0), z.lte(100)).register(z.globalRegistry, {
     description: "Page size. Max 100."
-  })), 20)
+  })), 20),
+  includeImported: z._default(z.optional(z.boolean().register(z.globalRegistry, {
+    description: "Also return posts imported from a connected platform (posts with source IMPORTED). Defaults to false: only posts created through PublishQ are returned."
+  })), false),
+  onlyImported: z._default(z.optional(z.boolean().register(z.globalRegistry, {
+    description: "Return ONLY posts imported from a connected platform. Cannot be combined with includeImported."
+  })), false)
 });
 var zListPostsResponse = zPostsResponse;
 var zCreatePostBody = zCreatePostRequest;
@@ -1865,6 +2000,12 @@ var zGetMediaPath = z.object({
   id: z.uuid()
 });
 var zGetMediaResponse = zMedia;
+var zCreateMediaUploadBody = zCreateMediaUploadRequest;
+var zCreateMediaUploadResponse = zMediaUpload;
+var zCompleteMediaUploadPath = z.object({
+  id: z.uuid()
+});
+var zCompleteMediaUploadResponse = zMedia;
 
 // src/index.ts
 var rawErrorBodies = /* @__PURE__ */ new WeakMap();
@@ -1966,12 +2107,92 @@ function createWorkspacesNamespace(client2) {
     get: (id) => preserveApiError(Workspaces.getWorkspace({ client: client2, path: { id } }))
   };
 }
+var UPLOAD_MIME_TYPE_BY_EXTENSION = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo"
+};
+function isUninformativeType(type) {
+  return type === "" || type === "application/octet-stream";
+}
+function withInferredContentType(file) {
+  const name = "name" in file ? file.name : void 0;
+  if (!name || !isUninformativeType(file.type)) return file;
+  const extension = name.split(".").pop()?.toLowerCase();
+  const type = extension ? UPLOAD_MIME_TYPE_BY_EXTENSION[extension] : void 0;
+  if (!type) return file;
+  return new File([file], name, { type });
+}
+var STORAGE_UPLOAD_THRESHOLD_BYTES = 90 * 1024 * 1024;
+async function uploadThroughStorage(client2, file) {
+  const created = await preserveApiError(
+    Media.createMediaUpload({
+      client: client2,
+      body: {
+        filename: "name" in file && file.name ? file.name : "upload",
+        contentType: file.type,
+        fileSize: file.size
+      }
+    })
+  );
+  if (!created.data) return created;
+  const response = await fetch(created.data.uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": file.type },
+    body: file
+  });
+  if (!response.ok) {
+    return {
+      data: void 0,
+      error: {
+        error: {
+          status: response.status,
+          message: "Storage refused the file upload",
+          mediaId: created.data.id,
+          storageResponse: await response.text()
+        }
+      },
+      request: new Request(created.data.uploadUrl, { method: "PUT" }),
+      response
+    };
+  }
+  return preserveApiError(
+    Media.completeMediaUpload({ client: client2, path: { id: created.data.id } })
+  );
+}
 function createMediaNamespace(client2) {
   return {
     /** List your uploaded and generated media files. Filter by id, type, source. Wraps `Media.listMedia`. */
     list: (query) => preserveApiError(Media.listMedia({ client: client2, query })),
-    /** Upload one media file (multipart) and get back a media ID to attach to posts. Wraps `Media.uploadMedia`. */
-    upload: (body) => preserveApiError(Media.uploadMedia({ client: client2, body })),
+    /**
+     * Upload one media file and get back a media ID to attach to posts. Wraps
+     * `Media.uploadMedia`, or for files over `STORAGE_UPLOAD_THRESHOLD_BYTES`
+     * runs `createUpload`, sends the file to storage and returns the finished
+     * media from `completeUpload`. Both return the same `Media` object.
+     *
+     * The file's content type is filled in from its name when it has none, so a
+     * file read off disk with `new File([buffer], 'photo.jpg')` is not sent as
+     * `application/octet-stream` and refused. See `withInferredContentType`.
+     */
+    upload: (body) => {
+      const file = withInferredContentType(body.file);
+      if (file.size > STORAGE_UPLOAD_THRESHOLD_BYTES) {
+        return uploadThroughStorage(client2, file);
+      }
+      return preserveApiError(
+        Media.uploadMedia({ client: client2, body: { ...body, file } })
+      );
+    },
+    /** Get a storage upload URL for a file of up to 4 GB. Send the file there, then use the returned media ID in posts. Wraps `Media.createMediaUpload`. */
+    createUpload: (body) => preserveApiError(Media.createMediaUpload({ client: client2, body })),
+    /** Add a file sent to a `createUpload` URL to the media library now and return it. Optional: using the ID in a post does the same. Wraps `Media.completeMediaUpload`. */
+    completeUpload: (id) => preserveApiError(Media.completeMediaUpload({ client: client2, path: { id } })),
     /** Get one media file by ID. Wraps `Media.getMedia`. */
     get: (id) => preserveApiError(Media.getMedia({ client: client2, path: { id } }))
   };
@@ -1983,13 +2204,20 @@ var index_default = PublishQ;
   Media2,
   Posts,
   PublishQ,
+  STORAGE_UPLOAD_THRESHOLD_BYTES,
   Workspaces,
+  withInferredContentType,
   zAccount,
   zAccountsResponse,
   zApiError,
   zApiErrorCode,
   zApiKeyScope,
   zBlueskyPlatformSpecificSettings,
+  zCompleteMediaUploadPath,
+  zCompleteMediaUploadResponse,
+  zCreateMediaUploadBody,
+  zCreateMediaUploadRequest,
+  zCreateMediaUploadResponse,
   zCreatePostAccount,
   zCreatePostBody,
   zCreatePostRequest,
@@ -2022,13 +2250,17 @@ var index_default = PublishQ;
   zMediaListResponse,
   zMediaSource,
   zMediaType,
+  zMediaUpload,
   zPagination,
   zPlatformSpecificSettings,
   zPost,
   zPostAccount,
+  zPostAnalytics,
   zPostOverrides,
+  zPostSource,
   zPostStatus,
   zPostsResponse,
+  zPublishFailure,
   zRemovePostAccountPath,
   zRemovePostAccountResponse,
   zSocialPlatform,