@articlesq/sdk 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -315,6 +315,7 @@ type Options$1<TData extends TDataShape = TDataShape, ThrowOnError extends boole
 type ClientOptions = {
     baseUrl: "https://articlesq.com/api/v1" | (string & {});
 };
+type Webhooks = ArticlePublishedWebhookRequest | ArticleUpdatedWebhookRequest | ArticleUnpublishedWebhookRequest;
 type ApiError = {
     error: {
         title: string;
@@ -329,7 +330,7 @@ type ApiError = {
         };
     };
 };
-type ApiErrorCode = "missing_auth" | "invalid_auth_format" | "invalid_api_key" | "api_key_expired" | "insufficient_scope" | "not_found" | "route_not_found" | "validation_failed" | "slug_conflict" | "internal_error";
+type ApiErrorCode = "missing_auth" | "invalid_auth_format" | "invalid_api_key" | "api_key_expired" | "insufficient_scope" | "forbidden" | "not_found" | "route_not_found" | "validation_failed" | "slug_conflict" | "internal_error";
 type Pagination = {
     /**
      * Current page number (starting from 1).
@@ -390,7 +391,7 @@ type Article = {
      */
     datePublished: string | null;
     /**
-     * Last meaningful content update (schema.org `dateModified`) as an ISO 8601 string. Null until the article is edited after being published.
+     * Last meaningful content update (schema.org `dateModified`) as an ISO 8601 string. Stamped automatically when a published article's content changes, and overridable from the dashboard for imported content. Null until either happens.
      */
     dateModified: string | null;
 };
@@ -454,6 +455,134 @@ type UpdateArticleBody = {
      */
     faq?: Array<FaqItem>;
 };
+type GenerateArticleImagesBody = {
+    cover?: CoverImagePrompt;
+    /**
+     * In-content images (16:9). Each one replaces its `{{IMAGE_N}}` marker in the article content with the generated image.
+     */
+    inline?: Array<InlineImagePrompt>;
+};
+/**
+ * Cover image (16:9). Replaces the current cover when the article already has one.
+ */
+type CoverImagePrompt = {
+    /**
+     * What the image shows: subject, action, setting, composition, and where the logo or character sits if you want a specific spot. The project's image style, its logo and character references, the placement rules and the project's brand notes are added to this prompt automatically, so describe the scene only.
+     */
+    prompt: string;
+    /**
+     * Alt text for the image. Also used to name the stored file, so write it the way someone would search for it.
+     */
+    alt: string;
+    /**
+     * Set to `false` to leave the logo and character out of this image (e.g. a clean diagram). Defaults to the project's image settings.
+     */
+    branding?: boolean;
+};
+type InlineImagePrompt = {
+    /**
+     * Marker this image replaces. Put `{{IMAGE_1}}` on its own line in the article content where the image belongs, then send `id: "IMAGE_1"`.
+     */
+    id: string;
+    /**
+     * What the image shows: subject, action, setting, composition, and where the logo or character sits if you want a specific spot. The project's image style, its logo and character references, the placement rules and the project's brand notes are added to this prompt automatically, so describe the scene only.
+     */
+    prompt: string;
+    /**
+     * Alt text for the image. Also used to name the stored file, so write it the way someone would search for it.
+     */
+    alt: string;
+    /**
+     * Set to `false` to leave the logo and character out of this image (e.g. a clean diagram). Defaults to the project's image settings.
+     */
+    branding?: boolean;
+};
+type ArticleImagesResponse = {
+    article: Article;
+    images: GenerateArticleImagesResult;
+};
+type GenerateArticleImagesResult = {
+    /**
+     * Ids of the images that were generated and saved.
+     */
+    generated: Array<string>;
+    /**
+     * Ids of the images that are not in the article after this call. Send an inline id again only if its `{{ID}}` marker is still in the returned `article.content`; if the marker is gone, another call already placed an image there. Send the cover again if `coverImage` did not change.
+     */
+    failed: Array<string>;
+};
+type ImageSettingsResponse = {
+    imageSettings: ImageSettings;
+};
+type ImageSettings = {
+    /**
+     * A preset id from `stylePresets`, or your own style description. Prepended to every image prompt. An empty string selects the default preset.
+     */
+    imageStyle: "" | string;
+    /**
+     * The style text that is actually added to prompts: the preset's description, or `imageStyle` itself when it is custom.
+     */
+    imageStyleDescription: string;
+    stylePresets: Array<StylePreset>;
+    /**
+     * Whether the project's logo is placed in generated images, once per image.
+     */
+    logoEnabled: boolean;
+    /**
+     * The logo image attached to image prompts: the AI-specific logo variation when one is uploaded, otherwise the project logo.
+     */
+    logoImageUrl: string | null;
+    /**
+     * Whether the project's character appears in generated images as the main character.
+     */
+    characterEnabled: boolean;
+    /**
+     * The character reference photo. Upload it from the dashboard's image settings.
+     */
+    characterImageUrl: string | null;
+    /**
+     * Brand notes added to every image prompt, e.g. where the logo goes or what the character wears.
+     */
+    instructions: string;
+};
+type StylePreset = {
+    id: string;
+    label: string;
+    description: string;
+};
+type UpdateImageSettingsBody = {
+    /**
+     * A preset id from `stylePresets`, or your own style description. Prepended to every image prompt. An empty string selects the default preset.
+     */
+    imageStyle?: "" | string;
+    logoEnabled?: boolean;
+    /**
+     * Requires a character photo on the project (`characterImageUrl`).
+     */
+    characterEnabled?: boolean;
+    /**
+     * Brand notes added to every image prompt. Pass an empty string to clear them.
+     */
+    instructions?: string;
+};
+type ArticleEvent = {
+    /**
+     * Which event fired. `article.published` on an article becoming public, `article.updated` on a content change to an already-published article, `article.unpublished` when it returns to draft and leaves the public API.
+     */
+    type: "article.published" | "article.updated" | "article.unpublished";
+    /**
+     * When the event was generated, ISO 8601. Matches the `webhook-timestamp` header (seconds since the epoch) used to sign the request.
+     */
+    timestamp: string;
+    /**
+     * Identifies the article that changed. Fetch `GET /articles/{slug}` for the current content: the event is a notification, not a snapshot.
+     */
+    article: {
+        id: string;
+        slug: string;
+        projectId: string;
+    };
+};
 type ListArticlesData = {
     body?: never;
     path?: never;
@@ -594,6 +723,122 @@ type UpdateArticleResponses = {
     200: ArticleResponse;
 };
 type UpdateArticleResponse = UpdateArticleResponses[keyof UpdateArticleResponses];
+type GenerateArticleImagesData = {
+    body: GenerateArticleImagesBody;
+    path: {
+        slug: string;
+    };
+    query?: never;
+    url: "/articles/{slug}/images";
+};
+type GenerateArticleImagesErrors = {
+    /**
+     * Invalid request body, or the content has no marker for an inline image
+     */
+    400: ApiError;
+    /**
+     * Invalid or missing API key
+     */
+    401: ApiError;
+    /**
+     * API key lacks the required scope
+     */
+    403: ApiError;
+    /**
+     * Article not found in this project
+     */
+    404: ApiError;
+};
+type GenerateArticleImagesError = GenerateArticleImagesErrors[keyof GenerateArticleImagesErrors];
+type GenerateArticleImagesResponses = {
+    /**
+     * Images generated and saved to the article
+     */
+    200: ArticleImagesResponse;
+};
+type GenerateArticleImagesResponse = GenerateArticleImagesResponses[keyof GenerateArticleImagesResponses];
+type GetImageSettingsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: "/image-settings";
+};
+type GetImageSettingsErrors = {
+    /**
+     * Invalid or missing API key
+     */
+    401: ApiError;
+    /**
+     * API key lacks the required scope
+     */
+    403: ApiError;
+};
+type GetImageSettingsError = GetImageSettingsErrors[keyof GetImageSettingsErrors];
+type GetImageSettingsResponses = {
+    /**
+     * Image settings retrieved successfully
+     */
+    200: ImageSettingsResponse;
+};
+type GetImageSettingsResponse = GetImageSettingsResponses[keyof GetImageSettingsResponses];
+type UpdateImageSettingsData = {
+    body: UpdateImageSettingsBody;
+    path?: never;
+    query?: never;
+    url: "/image-settings";
+};
+type UpdateImageSettingsErrors = {
+    /**
+     * Invalid request body, or the character was enabled without a character photo
+     */
+    400: ApiError;
+    /**
+     * Invalid or missing API key
+     */
+    401: ApiError;
+    /**
+     * API key lacks the required scope
+     */
+    403: ApiError;
+};
+type UpdateImageSettingsError = UpdateImageSettingsErrors[keyof UpdateImageSettingsErrors];
+type UpdateImageSettingsResponses = {
+    /**
+     * Image settings updated
+     */
+    200: ImageSettingsResponse;
+};
+type UpdateImageSettingsResponse = UpdateImageSettingsResponses[keyof UpdateImageSettingsResponses];
+/**
+ * Event payload
+ */
+type ArticlePublishedWebhookPayload = ArticleEvent;
+type ArticlePublishedWebhookRequest = {
+    body: ArticlePublishedWebhookPayload;
+    key: "article.published";
+    path?: never;
+    query?: never;
+};
+/**
+ * Event payload
+ */
+type ArticleUpdatedWebhookPayload = ArticleEvent;
+type ArticleUpdatedWebhookRequest = {
+    body: ArticleUpdatedWebhookPayload;
+    key: "article.updated";
+    path?: never;
+    query?: never;
+};
+/**
+ * Event payload
+ */
+type ArticleUnpublishedWebhookPayload = ArticleEvent;
+type ArticleUnpublishedWebhookRequest = {
+    body: ArticleUnpublishedWebhookPayload;
+    key: "article.unpublished";
+    path?: never;
+    query?: never;
+};
 
 type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options$1<TData, ThrowOnError, TResponse> & {
     /**
@@ -633,6 +878,26 @@ declare class Articles {
      * Update editable fields on an article — currently `content` and `metaDescription`. Send only the fields you want to change. Returns the full updated article.
      */
     static updateArticle<ThrowOnError extends boolean = false>(options: Options<UpdateArticleData, ThrowOnError>): RequestResult<UpdateArticleResponses, UpdateArticleErrors, ThrowOnError, "fields">;
+    /**
+     * Generate article images
+     *
+     * Generates the cover and in-content images for an article from your prompts, stores them and puts them into the article. Write `{{IMAGE_1}}`, `{{IMAGE_2}}`, ... on their own lines in the content where each image belongs, then send one prompt per marker. Each prompt describes the scene; ArticlesQ adds the project's image style, its logo and character (following the project's image settings, see `GET /image-settings`) and the project's brand notes. Images are generated in parallel and the response returns the updated article. To replace an in-content image, put its marker back in the content with `PATCH /articles/{slug}` and send its prompt again.
+     */
+    static generateArticleImages<ThrowOnError extends boolean = false>(options: Options<GenerateArticleImagesData, ThrowOnError>): RequestResult<GenerateArticleImagesResponses, GenerateArticleImagesErrors, ThrowOnError, "fields">;
+}
+declare class Images {
+    /**
+     * Get image settings
+     *
+     * Returns the project's image settings: the style added to every image prompt, whether the logo and the character are used, their reference images, and the brand notes. Read them before writing image prompts so your scenes fit the style and the brand notes.
+     */
+    static getImageSettings<ThrowOnError extends boolean = false>(options?: Options<GetImageSettingsData, ThrowOnError>): RequestResult<GetImageSettingsResponses, GetImageSettingsErrors, ThrowOnError, "fields">;
+    /**
+     * Update image settings
+     *
+     * Update the project's image style, turn the logo or the character on or off, or edit the brand notes. Send only the fields you want to change. Returns the full image settings.
+     */
+    static updateImageSettings<ThrowOnError extends boolean = false>(options: Options<UpdateImageSettingsData, ThrowOnError>): RequestResult<UpdateImageSettingsResponses, UpdateImageSettingsErrors, ThrowOnError, "fields">;
 }
 
 interface ArticlesQOptions {
@@ -670,6 +935,11 @@ declare class ArticlesQ {
      * key is scoped to.
      */
     readonly articles: ReturnType<typeof createArticlesNamespace>;
+    /**
+     * The project's image settings: style, logo, character and brand notes
+     * that ArticlesQ adds to every generated image.
+     */
+    readonly imageSettings: ReturnType<typeof createImageSettingsNamespace>;
     constructor(options: ArticlesQOptions);
 }
 declare function createArticlesNamespace(client: Client): {
@@ -731,6 +1001,51 @@ declare function createArticlesNamespace(client: Client): {
         request?: Request;
         response?: Response;
     }>;
+    /**
+     * Generate the cover and in-content images for an article from your
+     * prompts. Wraps `Articles.generateArticleImages`.
+     *
+     * Put `{{IMAGE_1}}`, `{{IMAGE_2}}`, ... in the content where each image
+     * belongs, then send one prompt per marker. The project's image style,
+     * logo, character and brand notes are added automatically.
+     */
+    generateImages: (slug: string, body: GenerateArticleImagesData["body"]) => Promise<({
+        data: ArticleImagesResponse;
+        error: undefined;
+    } | {
+        data: undefined;
+        error: ApiError;
+    }) & {
+        request?: Request;
+        response?: Response;
+    }>;
+};
+declare function createImageSettingsNamespace(client: Client): {
+    /** Read the project's image settings. Wraps `Images.getImageSettings`. */
+    get: () => Promise<({
+        data: ImageSettingsResponse;
+        error: undefined;
+    } | {
+        data: undefined;
+        error: ApiError;
+    }) & {
+        request?: Request;
+        response?: Response;
+    }>;
+    /**
+     * Update the image style, the logo/character toggles or the brand notes.
+     * Wraps `Images.updateImageSettings`.
+     */
+    update: (body: UpdateImageSettingsData["body"]) => Promise<({
+        data: ImageSettingsResponse;
+        error: undefined;
+    } | {
+        data: undefined;
+        error: ApiError;
+    }) & {
+        request?: Request;
+        response?: Response;
+    }>;
 };
 
-export { type ApiError, type ApiErrorCode, type Article, type ArticleResponse, type ArticleStatus, Articles, ArticlesQ, type ArticlesQOptions, type ClientOptions, type CreateArticleBody, type CreateArticleData, type CreateArticleError, type CreateArticleErrors, type CreateArticleResponse, type CreateArticleResponses, type FaqItem, type GetArticleData, type GetArticleError, type GetArticleErrors, type GetArticleResponse, type GetArticleResponses, type ListArticlesData, type ListArticlesError, type ListArticlesErrors, type ListArticlesResponse, type ListArticlesResponse2, type ListArticlesResponses, type Options, type Pagination, type UpdateArticleBody, type UpdateArticleData, type UpdateArticleError, type UpdateArticleErrors, type UpdateArticleResponse, type UpdateArticleResponses, ArticlesQ as default };
+export { type ApiError, type ApiErrorCode, type Article, type ArticleEvent, type ArticleImagesResponse, type ArticlePublishedWebhookPayload, type ArticlePublishedWebhookRequest, type ArticleResponse, type ArticleStatus, type ArticleUnpublishedWebhookPayload, type ArticleUnpublishedWebhookRequest, type ArticleUpdatedWebhookPayload, type ArticleUpdatedWebhookRequest, Articles, ArticlesQ, type ArticlesQOptions, type ClientOptions, type CoverImagePrompt, type CreateArticleBody, type CreateArticleData, type CreateArticleError, type CreateArticleErrors, type CreateArticleResponse, type CreateArticleResponses, type FaqItem, type GenerateArticleImagesBody, type GenerateArticleImagesData, type GenerateArticleImagesError, type GenerateArticleImagesErrors, type GenerateArticleImagesResponse, type GenerateArticleImagesResponses, type GenerateArticleImagesResult, type GetArticleData, type GetArticleError, type GetArticleErrors, type GetArticleResponse, type GetArticleResponses, type GetImageSettingsData, type GetImageSettingsError, type GetImageSettingsErrors, type GetImageSettingsResponse, type GetImageSettingsResponses, type ImageSettings, type ImageSettingsResponse, Images, type InlineImagePrompt, type ListArticlesData, type ListArticlesError, type ListArticlesErrors, type ListArticlesResponse, type ListArticlesResponse2, type ListArticlesResponses, type Options, type Pagination, type StylePreset, type UpdateArticleBody, type UpdateArticleData, type UpdateArticleError, type UpdateArticleErrors, type UpdateArticleResponse, type UpdateArticleResponses, type UpdateImageSettingsBody, type UpdateImageSettingsData, type UpdateImageSettingsError, type UpdateImageSettingsErrors, type UpdateImageSettingsResponse, type UpdateImageSettingsResponses, type Webhooks, ArticlesQ as default };

package/dist/index.js

@@ -872,6 +872,52 @@ var Articles = class {
       }
     });
   }
+  /**
+   * Generate article images
+   *
+   * Generates the cover and in-content images for an article from your prompts, stores them and puts them into the article. Write `{{IMAGE_1}}`, `{{IMAGE_2}}`, ... on their own lines in the content where each image belongs, then send one prompt per marker. Each prompt describes the scene; ArticlesQ adds the project's image style, its logo and character (following the project's image settings, see `GET /image-settings`) and the project's brand notes. Images are generated in parallel and the response returns the updated article. To replace an in-content image, put its marker back in the content with `PATCH /articles/{slug}` and send its prompt again.
+   */
+  static generateArticleImages(options) {
+    return (options.client ?? client).post({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/articles/{slug}/images",
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+  }
+};
+var Images = class {
+  /**
+   * Get image settings
+   *
+   * Returns the project's image settings: the style added to every image prompt, whether the logo and the character are used, their reference images, and the brand notes. Read them before writing image prompts so your scenes fit the style and the brand notes.
+   */
+  static getImageSettings(options) {
+    return (options?.client ?? client).get({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/image-settings",
+      ...options
+    });
+  }
+  /**
+   * Update image settings
+   *
+   * Update the project's image style, turn the logo or the character on or off, or edit the brand notes. Send only the fields you want to change. Returns the full image settings.
+   */
+  static updateImageSettings(options) {
+    return (options.client ?? client).patch({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/image-settings",
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+  }
 };
 
 // src/index.ts
@@ -881,6 +927,11 @@ var ArticlesQ = class {
    * key is scoped to.
    */
   articles;
+  /**
+   * The project's image settings: style, logo, character and brand notes
+   * that ArticlesQ adds to every generated image.
+   */
+  imageSettings;
   constructor(options) {
     const client2 = createClient(
       createConfig({
@@ -891,6 +942,7 @@ var ArticlesQ = class {
       })
     );
     this.articles = createArticlesNamespace(client2);
+    this.imageSettings = createImageSettingsNamespace(client2);
   }
 };
 function createArticlesNamespace(client2) {
@@ -916,13 +968,34 @@ function createArticlesNamespace(client2) {
      * Send only the fields you want to change (currently `content` and
      * `metaDescription`). Returns the full updated article on success.
      */
-    update: (slug, body) => Articles.updateArticle({ client: client2, path: { slug }, body })
+    update: (slug, body) => Articles.updateArticle({ client: client2, path: { slug }, body }),
+    /**
+     * Generate the cover and in-content images for an article from your
+     * prompts. Wraps `Articles.generateArticleImages`.
+     *
+     * Put `{{IMAGE_1}}`, `{{IMAGE_2}}`, ... in the content where each image
+     * belongs, then send one prompt per marker. The project's image style,
+     * logo, character and brand notes are added automatically.
+     */
+    generateImages: (slug, body) => Articles.generateArticleImages({ client: client2, path: { slug }, body })
+  };
+}
+function createImageSettingsNamespace(client2) {
+  return {
+    /** Read the project's image settings. Wraps `Images.getImageSettings`. */
+    get: () => Images.getImageSettings({ client: client2 }),
+    /**
+     * Update the image style, the logo/character toggles or the brand notes.
+     * Wraps `Images.updateImageSettings`.
+     */
+    update: (body) => Images.updateImageSettings({ client: client2, body })
   };
 }
 var index_default = ArticlesQ;
 export {
   Articles,
   ArticlesQ,
+  Images,
   index_default as default
 };
 //# sourceMappingURL=index.js.map