Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,44 @@ Simply Static remains responsible for crawling WordPress and rewriting URLs.
Spacefast never reads drafts, WordPress credentials, or the database. Dynamic
WordPress features still need a static-compatible replacement.

### Review, publish, and roll back

Enable **Review before going live** under **Settings → Spacefast → WordPress
sync** to stage exports. The default is off: existing sites continue publishing
directly to live. When enabled, manual, automatic, and partial exports all wait
for approval. Partial exports remain additive and preserve omitted files.

After an export completes, the **Staged version** card shows added, changed, and
removed file counts. **Open preview** opens that version in a new tab. **Copy
preview link** creates a link for a reviewer; it grants access to that version
for 10 minutes. Generate a fresh link after it expires. **Go live** promotes the
reviewed version. **Discard** permanently deletes that staged version, leaving
the live site alone. A later export replaces the staged card; earlier ready
versions remain in history.

**Versions** lists the latest 20 versions with their time, file count, live
status, and manual/automatic source for exports recorded by this installation.
Older or externally published versions show an unknown source. Use **Make live**
to roll back to an earlier ready version. Promotion uses Spacefast's default
rewrite refresh and records the returned version ID, including when rollback
creates a new version from the old files. If Spacefast asks for a person to
approve a promotion, a **Waiting for approval** card links to the approval in
Spacefast; after approving, choose **Finish** to resend the same request. The
continuation token stays on the server and is never shown. API failures leave
the staged receipt available for retry. A full staged export after a deletion must go live before
partial publishing resumes.

Editors (`edit_others_posts`) can stage and preview when review is enabled on a
connected static site. Administrators (`manage_options`) can promote, roll back,
and discard. The `spacefast_wordpress_can_promote` filter receives the default
capability result and can restrict or delegate those version actions; it does
not grant access to connection settings.

Existing static connections must **Reconnect Spacefast** once for previews and
promotion. New connections request `publish:write`: Spacefast's scope mapping
includes `versions:promote` and `versions:download` (required by preview sessions).
The old `spaces:publish` scope grants only publishing. Headless scopes are unchanged.

## Headless CMS

Open **Use WordPress as a CMS for a repository site** when an Astro or other repository project reads the
Expand Down
46 changes: 42 additions & 4 deletions includes/class-spacefast-client.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ public function __construct( ?callable $transport = null, ?callable $upload_tran
/**
* @return array{ok:bool,retryable:bool,code:string,message:string,data:array<string,mixed>}
*/
private function request( string $method, string $path, ?array $body = null, array $headers = array() ): array {
private function request( string $method, string $path, ?array $body = null, array $headers = array(), int $timeout = 10 ): array {
$settings = Spacefast_Settings::get();
$access_token = ( new Spacefast_OAuth( $this->transport ) )->access_token();
if ( '' === $access_token ) {
Expand All @@ -30,7 +30,7 @@ private function request( string $method, string $path, ?array $body = null, arr
}
$args = array(
'method' => $method,
'timeout' => 10,
'timeout' => $timeout,
'redirection' => 0,
'reject_unsafe_urls' => true,
'sslverify' => true,
Expand Down Expand Up @@ -69,6 +69,7 @@ private function request( string $method, string $path, ?array $body = null, arr
if (
$status >= 200
&& $status < 300
&& ! ( 'DELETE' === $method && 204 === $status )
&& ( '' === $raw_body || JSON_ERROR_NONE !== json_last_error() || ! is_array( $decoded ) )
) {
return array(
Expand Down Expand Up @@ -110,6 +111,8 @@ private function request( string $method, string $path, ?array $body = null, arr
? 'The Spacefast connection is no longer authorized.'
: (string) ( $decoded['detail'] ?? 'Spacefast rejected the request.' ),
'data' => array(),
// Error details carry follow-up steps such as an approval link.
'details' => isset( $decoded['details'] ) && is_array( $decoded['details'] ) ? $decoded['details'] : array(),
);
}

Expand Down Expand Up @@ -273,15 +276,18 @@ public function get_build( string $build_id ): array {
* @param array<int,array{path:string,size:int,sha256:string,contentType:string}> $files Files.
* @return array{ok:bool,retryable:bool,code:string,message:string,data:array<string,mixed>}
*/
public function create_static_version( array $files, string $event_id, string $publish_mode ): array {
public function create_static_version( array $files, string $event_id, string $publish_mode, ?string $channel = 'live' ): array {
if ( null !== $channel && 'live' !== $channel ) {
throw new InvalidArgumentException( 'Static publish channel is invalid.' );
}
$settings = Spacefast_Settings::get();
return $this->request(
'POST',
'/v1/spaces/' . rawurlencode( $settings['space_id'] ) . '/versions',
array(
'publishMode' => $publish_mode,
'files' => $files,
'finalize' => array( 'channel' => 'live' ),
'finalize' => array( 'channel' => $channel ),
'source' => array(
'kind' => 'api',
'client' => 'spacefast-wordpress/' . SPACEFAST_WORDPRESS_VERSION,
Expand All @@ -300,6 +306,38 @@ public function create_static_version( array $files, string $event_id, string $p
/**
* @return array{ok:bool,retryable:bool,code:string,message:string,data:array<string,mixed>}
*/
public function list_versions( int $limit = 20 ): array {
$settings = Spacefast_Settings::get();
return $this->request( 'GET', '/v1/spaces/' . rawurlencode( $settings['space_id'] ) . '/versions?limit=' . max( 1, min( 20, $limit ) ) );
}

public function preview_session( string $version_id, string $landing_path = '/' ): array {
return $this->request( 'POST', $this->version_path( $version_id ) . '/preview-session', array( 'landingPath' => $landing_path ) );
}

/**
* @param string $idempotency_key Reused when an approved promotion is resent.
* @param string $continuation_token Token from an approved confirmation_required response.
*/
public function promote_version( string $version_id, string $idempotency_key = '', string $continuation_token = '' ): array {
$headers = array();
if ( '' !== $idempotency_key ) $headers['Idempotency-Key'] = $idempotency_key;
if ( '' !== $continuation_token ) $headers['X-Spacefast-Continuation-Token'] = $continuation_token;
// Leave refreshRewrites at the server default, including for rollback.
return $this->request( 'POST', $this->version_path( $version_id ) . '/promote', array( 'channel' => 'live' ), $headers, 120 );
}

public function delete_version( string $version_id ): array {
return $this->request( 'DELETE', $this->version_path( $version_id ) );
}

private function version_path( string $version_id ): string {
if ( ! preg_match( '/^ver_[A-Za-z0-9_-]+$/', $version_id ) ) {
throw new InvalidArgumentException( 'Version ID is invalid.' );
}
return '/v1/spaces/' . rawurlencode( Spacefast_Settings::get()['space_id'] ) . '/versions/' . rawurlencode( $version_id );
}

public function resume_static_upload( string $version_id ): array {
$settings = Spacefast_Settings::get();
return $this->request(
Expand Down
4 changes: 3 additions & 1 deletion includes/class-spacefast-oauth.php
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@ public function __construct( ?callable $transport = null ) {

/** @return array<int,string> */
public static function scopes( string $mode ): array {
// spaces:publish alone excludes versions:promote and versions:download.
// publish:write includes both, including preview-session access.
return Spacefast_Settings::MODE_STATIC === $mode
? array( 'teams:read', 'spaces:read', 'spaces:write', 'spaces:publish', 'offline_access' )
? array( 'teams:read', 'spaces:read', 'spaces:write', 'publish:write', 'offline_access' )
: array( 'teams:read', 'spaces:read', 'spaces:write', 'builds:trigger', 'offline_access' );
}

Expand Down
Loading