Cosmic Changelog

We are excited to roll out new updates to the Cosmic NPM module (v4.2.*). This update adds new chain-style methods (Note: there are no breaking changes). Review the updates below.

Getting Started

Get started by installing the latest module version npm install cosmicjs@latest then import the package into your app.

Then set your Bucket slug and read key. These can be found in Your Bucket > Settings > API Access after logging in to your Cosmic dashboard.

Now use the new chain methods to find, add, edit, and delete Objects and Media in your Bucket.

Changes

• Updated the NPM module to v4.2.*
• Chain methods are now available
• Breaking changes: none

What's new

1. Added chain methods for Objects:

• bucket.objects.find
• bucket.objects.findOne
• bucket.objects.insertOne
• bucket.objects.updateOne
• bucket.objects.deleteOne

2. Added chain methods for Media:

• bucket.media.find
• bucket.media.findOne
• bucket.media.insertOne
• bucket.media.deleteOne

Old methods

For the old npm-v4.1.19 methods, see the docs version for npm-v4.1.19. These methods include:

1. Objects

• bucket.getObjects
• bucket.getObject
• bucket.addObject
• bucket.editObject
• bucket.deleteObject

2. Media

• bucket.getMedia
• bucket.getSingleMedia
• bucket.addMedia
• bucket.deleteMedia

We hope you enjoy these new methods for using the Cosmic NPM module. Review all of the methods now available in the Cosmic docs. To stay up with the latest updates to Cosmic, follow us on Twitter, subscribe on YouTube, join us on Slack.

We've added new examples to the Cosmic documentation to help you learn common Cosmic API methods and use cases. The new examples feature simple copy + paste code for Node.js, cURL, GraphQL, and the Cosmic CLI.

You can run the following code as is or add your Bucket access keys to connect to your Bucket content. Learn all of the available examples and follow along with the code examples below which use the Cosmic NPM module.

Go to the Cosmic docs to check out the new examples.

Setup & running Node.js

To run the following code examples, make sure you have Node.js installed on your machine. Then run the following setup commands in your terminal to make the Cosmic NPM module available in a new Node.js project:

mkdir cosmic-example
cd cosmic-example
yarn add cosmicjs

Add any of the code examples below to an index.js file and run node to see the results:

node index.js

Basic queries

The basic queries show you how to get a list of Objects in your Bucket by Object Type as well as getting a single Object in your Bucket by Object slug.

Get Objects by type:

Get single Object by slug:

Advanced queries

The advanced queries show you some of the capabilities to get content by more detailed search options such as metadata values, $gte (greater than or equal to), $lte(less than or equal to), $ne (not equal to), and more.

Search Objects by metadata value:

Search Objects by metadata number value less than or equal to using $lte:

Search Objects not equal to metadata value using $ne:

Check out more examples of advanced queries in the docs.

Other Examples

Other examples include adding a new Object and uploading media using React Dropzone.  Copy + paste the code, add your Bucket access keys, and run the code to learn how to add content to your Cosmic Bucket.

We hope you enjoy these additions to our extensive documentation to help you better implement Cosmic-powered content into your websites and apps. Check out the Cosmic docs examples section and let us know what you think!

Cosmic Functions, which we announced back in 2018, is now scheduled for deprecation.

When will it be removed?
If you have used this feature, it is scheduled for removal in the current dashboard (and will not be included in the new dashboard).

You can continue to use the feature until the removal date. The date for removal from all new and existing Buckets is March 29, 2022*

* This will not affect any aspects of the core content management product or service.
** If you have already deployed functions to your AWS account through Cosmic, this will not affect the status of those functions. You will still be able to manage your functions through AWS.

Why is it being deprecated?
At the time we released Cosmic Functions, there were not a lot of options to deploy simple serverless functions easily in a dashboard interface. We actually used it quite a bit for some use cases internally, but they proved to not be very useful for our customers. And today there appears to be more (better) options in the marketplace for serverless function deployment including Serverless, Netlify, Vercel, and more.

We have decided to sunset the feature so we can focus more efforts on our core content management and delivery products and services.

Contact Us
If you have any questions or concerns about the removal of this feature please contact support.

Thank you,
Tony Spiro
Cosmic CEO

You can now set props on webhooks to limit the data payload. This is useful for Objects with large data payloads as it allows you to limit the payload to just the data you need.

How to use the new feature
See the props section in the Cosmic docs to learn more about how to use props. Go to Your Bucket > Settings > Webhooks after logging in to use the new feature.

Let's look at a couple of example webhook payloads with and without props.

Without Props
You get the full data payload.

That's a lot of data! Do you need it all? Maybe not. Enter props.

With Props
Get only the data you need. This example sets slug,title,metadata

Go to Bucket Settings > Webhooks to set props.

Wow, that's nice! Notice how much more concise the data payload is compared to not using props. Keep in mind that this currently only applies to first-level props (namespaced metadata declarations are not supported yet).

We hope you enjoy this quick update to make your automated workflows with webhooks more efficient. If you have any questions, please join the conversation in the Cosmic Slack channel and reach out to us on Twitter.

New usage graphs in the dashboard 📊

We are thrilled to tell you that Cosmic is growing faster than ever. As we serve an ever-increasing amount of content to billions of users globally we will continue to scale and provide you with the best content management experience in the world. To that end, we are implementing a new usage and overage policy, specifically the usage of our global CDN.

Our global CDN includes several points of presence located around the world to serve API and media resources blazing-fast within milliseconds. Along with our generous usage limits of non-cached API requests and media storage, we have added additional usage verticals of our global CDN which include:

1. Cached API requests - Number of read requests after initial request per month
2. Media requests - Number of media requests per month
3. API bandwidth - Amount of API bandwidth served per month
4. Media bandwidth - Amount of media bandwidth served per month

Pricing page updates
Go to the pricing page to see the new overage policy and applicable costs for each usage plan. We have provided very generous limits on all plans and include a new table to inform you about the new overage costs.

New usage graphs
To track your Bucket usage, go to Bucket Settings > Usage to see new usage graphs.

Overage costs
If you are one of the few customers that will have overage costs, you will be charged at the start of the month for the full overage usage of the previous month. The first overage invoices will go out at the start of August for July 2021 usage.

To see any upcoming month-to-date overage invoices, go to Bucket / Group Plan Settings > Billing (or Account Settings > Billing Details if you added a plan since our Billing update).

To avoid overage charges, you can always upgrade to the next usage plan level at any time. Reach out to sales@cosmicjs.com if you need a custom quote.

We are dedicated to providing you with the best content management experience in the world. And these updates are intended to help you track and scale your global content delivery as your business meets the demands of the growing digital economy.

If you have any questions about this policy update, you can reach out to me directly in the Cosmic Slack channel or by email.

Tony Spiro
Cosmic CEO

We've made some dashboard updates that should make managing account information, billing, and payment methods on your Cosmic account much easier. To get started, go to Account Settings > Billing Details to set up your payment methods and manage your global billing for your Cosmic products and services.

New Payment Methods Manager
You can now add and manage payment methods directly on your user account from your account settings area. Before, billing for Buckets was handled on the Bucket settings page. Now, with payment methods managed by your user account, you can manage billing for multiple Buckets and add-ons without re-entering payment information. Plus, you can now use Google Pay!

Go to Account Settings > Billing Details to set up your payment methods.

Add Billing Details
Along with this new way of managing your billing and payment methods, you can now update the name, email, and additional information that will be available on your invoices. Payment history will also be available on your account Billing Details page. (For the old Bucket billing, you will still see payment history on the Bucket billing page)

Group Plans for Bulk Rate
Group plans (formally called Billing Packages) are available for grouping Bucket usage plans onto a single cost-savings bulk-rate plan. Choose between 5 and 10 Buckets, plus a 10% discount for yearly plans.

Transfer Billing
Transfering billing between members of your team is now easier than ever. To have another team member take over billing, simply have them click "Transfer Billing" and the billing will switch to their account. (Team members must have admin access on the Bucket to transfer billing). See screenshot below.

We hope you enjoy these updates to make it easier to manage your account and billing details. If you have any questions, you can reach out to us at support@cosmicjs.com

We have some exciting updates to share with you which includes:

1. Documentation improvements: Client tabs, better nav, and more
2. New versions of the GraphQL, NPM, and CLI clients
3. New GraphQL API Postman collection
4. Ability to ignore the cache (handy for real-time updates)
5. Dashboard updates

Read more about the updates below, or jump over to the updated docs to get started. Go to the docs →

Updates

1. Documentation
Our new documentation website just got a lot better. We've added new tabs to show you the multiple methods for each resource including REST, Node.js, GraphQL, and the CLI.

2. New client versions
We have new GraphQL API (v3), NPM (v4), and CLI (v2) versions available that parallel the new features in the REST API v2 and follow the same request and response formats. See the docs changelog for the updates.

3. Postman collection for GraphQL API
Along with the REST API, we now have a Postman collection for the GraphQL API.

4. Ignore cache (real-time updates)
You can now ignore the cache for your API requests by setting use_cache=false as a query parameter in your GET requests. Why would you want to ignore our globally-fast CDN? This is helpful if you are doing real-time updates. For example, if you make an update to Object and immediately want to return the updated Object (as the cache takes ~200ms to purge).

5. Dashboard quality of life improvements
We've updated the Bucket settings page to include links to each section. We think this is a more helpful way to organize your Bucket settings.

We hope you enjoy these new updates. Head over to the new documentation site to check out all of these updates. And ping us in Slack if you have any questions.

We are excited to introduce Cosmic REST API v2 (alpha). The API has been rebuilt from the ground up to be lighter, faster, with lots of new features to make building Cosmic-powered apps even better.

Along with this release, we've built a brand new documentation site to help you learn more about all the new features. We recommend you start there to get all the latest and greatest in this release. Read below to get a breakdown of the new features, improvements, and changes.

New Features

• Nested metadata props are now possible without limit. See examples of nested props.
• No depth limit for Object relationships. The only limit is the prevention of infinite recursion.
• We now offer a Postman collection to review and demo all REST API methods.
• You can now use the after param for Object pagination.
• We now have endpoints for Metafields and Media Folders to do CRUD operations directly.

Improvements

• Lighter codebase, faster endpoints. In some cases, endpoint response times are up to 50% faster (non-cached).
• Better endpoint structures that follow standard REST conventions such as POST /resources, GET /resources/:resource_id, etc.
• Consistent error responses with verbose messages.
• The Select Dropdown Metafield now includes both key and value in the API response.

Changes

• _id has been changed to id.
• type_slug has been changed to type.
• status can now either be published or any (which returns latest Object version draft or published).
• query is now the primary method for fetching and filtering Objects (Advanced Queries from v1). See Queries and Logic for examples.
• Single Objects must now be fetched using id. To fetch by slug, you will need to use query.
• write_key will now be required in the request header as Authorization Bearer.
• metafields are hidden by default.
• Stricter user input requirements. No additional fields are possible in the body for POST and PATCH requests.
• There is a new, more secure token authentication strategy.

Next Steps

Read the docs to learn more about all the updates and improvements. We would appreciate your input as we get the REST API v2 ready for production. If you have any comments or questions, please drop them in the comments below or in our Slack channel.

- Cosmic Team

We've made a few big changes to the dashboard and API recently:

Projects
Projects are a new way to connect Buckets for use with Merge Requests. To do merges between Buckets they must be in the same Project. If you have Buckets that were created prior to the Merge Request release, you can clone any Bucket to create a new Project.

Clone Bucket from Settings
You can now clone any Bucket from the settings area by going to Settings > Basic Settings in the left sidebar, scroll down, and click "Clone Bucket". The Bucket will be cloned into the same Project (if it's not connected to a Project, a new one will be created).

Merge Requests

Merge Requests was the big release that we announced on Tuesday this week. Merge Requests enables you to do Git-like workflows for content. Perform bulk edits between Buckets, preview, include your team for approval workflows, and more. 

With this feature becoming a first-class feature in the Cosmic workflow, we've removed a previously released feature to copy Objects to another Bucket from the Objects table.

Merge Request Preview Link
You now have the ability to add a Merge Request preview link to your Bucket by going to Settings > Basic Settings and scrolling down to Merge Request Preview Link (only available on Buckets in a Project). This will be the default link added to all merge requests that make this Bucket the target Bucket.

Webhooks
There is a new webhook event available for merge.completed. This will only be triggered by the target Bucket. To set this up, in your Bucket go to Settings > Webhooks. See the docs for more info.

Singleton Object Type
Object Types can now be a singleton. A singleton Object Type is any type of content that only has one Object. For example Home Page, Site Settings, etc. As opposed to Blog Posts, Pages, etc. which are multiple Object Types.

API Updates
You can now get Merge Request Objects from the API to perform diffs against Objects in your target Bucket. See the docs for more info.

We hope you find these updates useful in your content workflows. It's our mission to make your use of Cosmic enjoyable and enables your team to do your best work. If you have any questions or comments, reach out to us on Twitter, and join us in Slack.